이 매뉴얼은 Gatrix 대시보드를 사용하는 게임 운영자를 위한 종합 가이드입니다.
| 장 | 제목 | 설명 |
|---|---|---|
| 1 | 소개 | Gatrix란 무엇인가? 주요 기능 개요, 다국어 안내 |
| 2 | 대시보드 개요 | 화면 구성, 환경 선택, 기본 조작법 |
| 2-1 | ⭐ 환경 관리 | 환경별 데이터 격리, 공유 정책, 환경 혼동 방지 |
| 장 | 제목 | 설명 |
|---|---|---|
| 3 | 사용자 관리 | 운영자 계정 생성, 권한 부여, 온/오프보딩 |
| 4 | 클라이언트 버전 관리 | 앱 버전 관리, 강제 업데이트, 스토어 심사 |
| 장 | 제목 | 설명 |
|---|---|---|
| 5 | 게임 월드 관리 | 서버 목록 관리, 월드별 상태 제어 |
| 6 | ⭐ 점검 관리 | 서비스/월드/버전별 점검, 화이트리스트 |
| 7 | 공지사항 관리 | 서비스 공지 작성, Rich Text Editor |
| 8 | 인게임 팝업 관리 | 긴급 안내, 팝업 우선순위 |
| 장 | 제목 | 설명 |
|---|---|---|
| 9 | 쿠폰 관리 | 쿠폰 발행, NORMAL/UNIQUE 유형 |
| 10 | 설문조사 관리 | 유저 설문, 참여 보상 |
| 장 | 제목 | 설명 |
|---|---|---|
| 11 | 상점 상품 관리 | IAP/인게임 상품 관리 |
| 12 | 배너 관리 | 시퀀스 기반 동적 배너 |
| 13 | 기획 데이터 관리 | Excel → JSON 변환, 버전 관리 |
| 14 | 리모트 컨피그 | 원격 설정, A/B 테스트 |
| 장 | 제목 | 설명 |
|---|---|---|
| 15 | 감사 로그 | 관리자 활동 추적, 보안 감사 |
| 16 | API 토큰 관리 | 서버 인증, 토큰 보안 |
| 항목 | 설명 |
|---|---|
| 환경 관리 | 환경별 데이터 격리/공유 정책, 환경 혼동 방지 가이드 |
| 점검 체계 | 서비스 전체/월드별/버전별 점검, 실시간 vs API 조회 |
| 화이트리스트 | 계정 ID, IP 주소 기반 (Device ID 미지원) |
| 다국어 안내 | 단일 국가 서비스 시 다국어 메시지 불필요 안내 |
| 트러블슈팅 | 각 기능별 문제 해결 케이스 추가 |
| 동영상 가이드 | 직접 재생 가능한 동영상 포함 |
manual/ko/
├── 00-table-of-contents.md # 이 파일 (목차)
├── 01-introduction.md # 소개 + 다국어 안내 + 영상
├── 02-dashboard.md # 대시보드 개요
├── 02-1-environments.md # ⭐ 환경 관리 (신규)
├── 03-user-management.md # 사용자 관리 + 트러블슈팅
├── 04-client-versions.md # 클라이언트 버전 + 트러블슈팅
├── 05-game-worlds.md # 게임 월드 관리
├── 06-maintenance.md # ⭐ 점검 관리 (대폭 보강)
├── 07-service-notices.md # 공지사항 + 트러블슈팅
├── 08-popup-notices.md # 인게임 팝업 관리
├── 09-coupons.md # 쿠폰 관리
├── 10-surveys.md # 설문조사 관리
├── 11-store-products.md # 상점 상품 관리
├── 12-banners.md # 배너 관리
├── 13-planning-data.md # 기획 데이터 관리
├── 14-remote-config.md # 리모트 컨피그
├── 15-audit-logs.md # 감사 로그
├── 16-api-tokens.md # API 토큰 관리
├── images/ # 스크린샷 이미지
└── videos/ # 동영상 가이드
| 상황 | 해당 장 |
|---|---|
| 신규 운영자 입사 | 3장: 사용자 관리 |
| 앱 업데이트 배포 | 4장: 클라이언트 버전 관리 |
| 긴급 점검 필요 | 6장: 점검 관리 |
| 이벤트 공지 작성 | 7장: 공지사항 관리 |
| 쿠폰 발급 | 9장: 쿠폰 관리 |
| 보안 감사 수행 | 15장: 감사 로그 |
| 환경 혼동 방지 | 2-1장: 환경 관리 |
Gatrix는 온라인 게임 서비스 운영에 필요한 모든 기능을 통합적으로 관리할 수 있는 게임 서비스 대시보드(Game Service Dashboard)입니다.
Gatrix를 통해 다음과 같은 업무를 수행할 수 있습니다:
- 게임 클라이언트 관리: 앱 버전 등록, 강제 업데이트 설정, 점검 모드 전환
- 게임 월드 관리: 게임 서버 등록 및 상태 관리 (혼잡도, 점검 중 표시 등)
- 플레이어 소통: 공지사항, 인게임 팝업, 설문조사 등을 통한 정보 전달
- 프로모션: 쿠폰 코드 발행, 배너 관리, 이벤트 진행
- 운영 모니터링: 서버 상태 확인, 관리자 활동 로그(Audit Log) 추적
- 실시간 제어: 클라이언트 패치 없이 게임 설정 변경 (Remote Config)
이 매뉴얼은 게임 서비스를 실제 운영하는 게임 서비스 담당자(GM, 운영자, QA, 사업 PM)를 위해 작성되었습니다.
주요 독자:
- 일일 게임 운영을 담당하는 운영자 (GM)
- 이벤트 및 프로모션을 기획하고 실행하는 사업 담당자
- 서버 점검 및 배포를 관리하는 기술 담당자
- 사용자 권한을 관리하는 최고 관리자
참고: 이 매뉴얼은 개발자가 아닌 사용자(운영자) 관점에서 작성되었습니다. SDK 연동 등 기술적인 내용은 포함되어 있지 않습니다.
Gatrix 대시보드는 최신 웹 표준을 준수하며, 다음 브라우저에서 최적화되어 있습니다:
- Google Chrome (권장)
- Microsoft Edge
- Mozilla Firefox
- Safari
🎬 영상 가이드: 로그인 방법 보기
처음이신가요? 관리자로부터 초대 메일을 받으셨다면, 메일 내 링크를 클릭하여 계정을 생성해 주세요.
초대 메일을 받은 후 계정을 생성하는 과정입니다.
🎬 영상 가이드: 회원가입 방법 보기
비밀번호를 잊으셨나요?
1. 로그인 화면에서 "비밀번호 찾기" 링크를 클릭하세요.
2. 가입한 이메일 주소를 입력하면 재설정 링크가 발송됩니다.
🎬 영상 가이드: 비밀번호 재설정 방법 보기
Gatrix와 클라이언트, 게임 서버 간의 상호작용 흐름입니다.
| 영역 | 설명 |
|---|---|
| 상단 헤더 | 로고, 환경 선택기, 알림, 프로필 메뉴 |
| 좌측 사이드바 | 메인 네비게이션 메뉴 |
| 중앙 콘텐츠 | 현재 페이지의 주요 내용 |
상단 헤더의 환경 선택기는 매우 중요합니다. 현재 작업 중인 환경이 어디인지 항상 확인하세요.
⚠️ 중요: 운영 환경(Production)에서의 변경 사항은 즉시 실제 유저들에게 반영됩니다. 작업 전에 반드시 상단의 환경 이름을 확인하세요!
대부분의 관리 페이지는 데이터 목록을 보여줍니다.
- 검색: 이름이나 ID로 항목을 찾습니다.
- 필터: 상태, 날짜 등으로 목록을 좁혀서 봅니다.
- 정렬: 컬럼 제목을 클릭하여 오름차순/내림차순 정렬합니다.
| 버튼 | 설명 |
|---|---|
| + 생성 / 추가 | 새로운 항목을 만듭니다. |
| 수정 (연필 아이콘) | 기존 내용을 변경합니다. |
| 삭제 (휴지통 아이콘) | 항목을 삭제합니다. (주의 필요) |
| 새로고침 | 최신 데이터로 목록을 갱신합니다. |
Gatrix는 공지사항, 점검 메시지, 팝업 등에서 다국어 메시지를 지원합니다.
💡 단일 국가에서만 서비스하는 경우, 다국어 메시지 설정은 필요하지 않습니다.
| 서비스 지역 | 다국어 메시지 | 권장 설정 |
|---|---|---|
| 한국 단독 | 불필요 | 기본 메시지만 입력 |
| 한국 + 일본 | 필요 | 한국어/일본어 입력 |
| 글로벌 | 필수 | 주요 언어 모두 입력 |
주요 기능별 동영상 가이드입니다. 각 영상을 클릭하여 재생할 수 있습니다.
클릭하여 새 창에서 재생하세요.
클릭하여 새 창에서 재생하세요.
클릭하여 새 창에서 재생하세요.
다음 장: 제 2장: 대시보드 개요 →
로그인 후 가장 먼저 만나는 화면이 바로 대시보드입니다. 현재 게임 서비스의 주요 지표와 상태를 한눈에 파악할 수 있도록 구성되어 있습니다.
상단에는 접속 시간에 따른 환영 인사와 로그인한 사용자의 이름, 역할(Admin/User)이 표시됩니다.
현재 환경의 주요 데이터 현황을 숫자로 보여줍니다. 각 카드를 클릭하면 해당 관리 페이지로 바로 이동합니다.
자주 사용하는 기능으로 바로 이동할 수 있는 단축 버튼입니다.
| 기능 | 설명 |
|---|---|
| 공지사항 (Service Notices) | 새로운 공지사항을 작성하거나 관리합니다. |
| 점검 (Maintenance) | 긴급 점검을 설정하거나 예정된 점검을 확인합니다. |
| 쿠폰 (Coupons) | 새로운 프로모션 쿠폰을 생성합니다. |
| 클라이언트 버전 | 앱 업데이트 정책을 변경합니다. |
운영 중인 모든 환경(Dev, Stage, Prod 등)의 데이터 개수를 요약해서 보여줍니다. 특정 환경에 데이터가 누락되지 않았는지 비교할 때 유용합니다.
누가, 언제, 무엇을 변경했는지 실시간 로그를 보여줍니다.
예: "관리자A님이 '주말 이벤트' 공지사항을 수정했습니다. (5분 전)"
팁: 더 자세한 전체 로그가 필요하다면 관리 > 감사 로그 (Audit Logs) 메뉴를 이용하세요.
최근 플레이어들에게 발생한 앱 충돌(Crash) 리포트 현황을 보여줍니다. 갑작스러운 크래시 증가를 모니터링하여 신속하게 대응할 수 있습니다.
현재 백엔드 서버들의 상태 신호(Heartbeat)를 보여줍니다.
- 🟢 Ready: 정상 작동 중
- 🔴 Stopped: 중지됨
- 🟡 Starting: 시작 중
현재 점검 중인 경우, 대시보드 상단에 "점검 중 (MAINTENANCE)" 배너가 큼지막하게 표시됩니다. 실수로 운영 중인 줄 알고 데이터를 조작하는 일을 방지해 줍니다.
눈의 피로를 줄이기 위해 다크 모드를 지원합니다.
대시보드 UI 언어를 변경할 수 있습니다.
1. 우측 상단 프로필 아이콘 클릭
2. 설정 (Settings) 선택
3. 언어(Language)에서 한국어, English, 中文 중 선택
💡 참고: 대시보드에 표시되는 데이터는 현재 상단에서 선택된 환경(Environment)에 대한 데이터입니다. 다른 환경의 현황을 보고 싶다면 상단 환경 선택기를 변경하세요.
이전 장: ← 제 1장: 소개
다음 장: 제 3장: 사용자 관리 →
Gatrix는 여러 환경(Environment)을 지원하여 개발, 테스트, 운영을 효과적으로 분리할 수 있습니다. 이 장에서는 환경별 데이터 격리와 공유 정책, 그리고 환경 혼동을 방지하는 방법을 설명합니다.
환경(Environment)은 독립된 데이터 공간입니다. 각 환경은 별도의 게임 서버, 설정, 콘텐츠를 가질 수 있습니다.
flowchart LR
subgraph 개발["🔧 Development"]
A[개발 테스트용<br/>데이터 자유롭게 수정]
end
subgraph 스테이징["🧪 Staging"]
B[배포 전 최종 확인<br/>운영과 유사한 환경]
end
subgraph 리뷰["📱 Review"]
C[스토어 심사용<br/>앱스토어/구글플레이]
end
subgraph 운영["🚀 Production"]
D[실제 유저 서비스<br/>⚠️ 변경 시 즉시 반영!]
end
개발 --> 스테이징 --> 운영
스테이징 --> 리뷰
style D fill:#ffcdd2
| 환경 | 용도 | 주의 수준 |
|---|---|---|
| Development | 새 기능 개발 및 테스트 | 🟢 낮음 |
| Staging | 배포 전 최종 검증 | 🟡 중간 |
| Review | 스토어 심사팀 접속용 | 🟡 중간 |
| CBT | 클로즈드 베타 테스트 | 🟡 중간 |
| Production | 실제 유저 서비스 | 🔴 높음 |
상단 헤더의 환경 선택 드롭다운에서 현재 작업 환경을 선택합니다.
⚠️ 경고: 환경 선택을 확인하지 않고 작업하면, 테스트용 데이터가 운영 환경에 등록되거나, 운영 데이터가 삭제되는 심각한 사고가 발생할 수 있습니다!
아래 데이터는 각 환경마다 별도로 관리됩니다. 한 환경에서 수정해도 다른 환경에 영향을 주지 않습니다.
| 데이터 | 설명 |
|---|---|
| 클라이언트 버전 | 환경별로 다른 버전 정책 가능 |
| 게임 월드 | 환경별 서버 목록 |
| 서비스 점검 | 환경별 점검 상태 |
| 공지사항 | 환경별 공지 내용 |
| 인게임 팝업 | 환경별 팝업 설정 |
| 쿠폰 | 환경별 쿠폰 발행 |
| 배너 | 환경별 배너 설정 |
| 기획 데이터 | 환경별 데이터 버전 |
| 리모트 컨피그 | 환경별 설정 값 |
flowchart TB
subgraph Dev["Development"]
A1[클라이언트 버전]
A2[공지사항]
A3[쿠폰]
end
subgraph Prod["Production"]
B1[클라이언트 버전]
B2[공지사항]
B3[쿠폰]
end
A1 -.->|❌ 공유 안됨| B1
A2 -.->|❌ 공유 안됨| B2
A3 -.->|❌ 공유 안됨| B3
style Dev fill:#e3f2fd
style Prod fill:#ffcdd2
아래 데이터는 모든 환경에서 공유됩니다. 한 곳에서 수정하면 모든 환경에 반영됩니다.
| 데이터 | 설명 |
|---|---|
| 사용자 계정 | 운영자 계정은 전역으로 관리 |
| 환경 접근 권한 | 사용자별 환경 접근 권한은 전역 설정 |
| API 토큰 | 환경 지정은 있지만 토큰 목록은 전역 조회 |
| 감사 로그 | 모든 환경의 활동이 통합 기록 |
| 화이트리스트 | 환경별로 별도 관리 가능하나 설정에 따라 공유 |
flowchart TB
subgraph 전역["🌐 전역 데이터"]
U[사용자 계정]
A[감사 로그]
T[API 토큰]
end
subgraph Dev["Development"]
D1[환경 데이터]
end
subgraph Prod["Production"]
P1[환경 데이터]
end
전역 --> Dev
전역 --> Prod
style 전역 fill:#c8e6c9
| 실수 | 결과 | 예방법 |
|---|---|---|
| Production에서 테스트 공지 등록 | 실제 유저에게 테스트 문구 노출 | 환경 확인 후 작업 |
| Dev에서 작업 후 Prod 미등록 | 운영에 콘텐츠 누락 | 체크리스트 사용 |
| Prod에서 데이터 삭제 테스트 | 실제 데이터 영구 삭제 | Dev에서 테스트 |
| 환경별 쿠폰 코드 혼동 | 잘못된 코드 배포 | 환경 명시 습관 |
작업 전:
- [ ] 상단 환경 선택기에서 현재 환경 확인
- [ ] Production인 경우 정말 필요한 작업인지 재확인
- [ ] 대용량 작업 시 먼저 Dev에서 테스트
작업 후:
- [ ] 의도한 환경에 데이터가 등록되었는지 확인
- [ ] 다른 환경에 잘못 등록되지 않았는지 확인
- [ ] Production 작업 시 팀원에게 공유
일부 데이터는 환경 간 복사가 가능합니다.
| 항목 | 방법 |
|---|---|
| 클라이언트 버전 | 목록에서 복사 버튼 → 대상 환경에서 붙여넣기 |
| 공지사항 | 수동으로 내용 복사 후 재등록 |
| 기획 데이터 | 동일 파일을 각 환경에 업로드 |
사용자마다 접근 가능한 환경을 제한할 수 있습니다.
flowchart TD
A[신규 입사자] --> B[Development만 접근]
B --> C[업무 숙련]
C --> D[Staging 접근 추가]
D --> E[Production 접근 승인]
style B fill:#c8e6c9
style E fill:#ffcdd2
| 역할 | Development | Staging | Review | Production |
|---|---|---|---|---|
| 신규 운영자 | ✅ | ❌ | ❌ | ❌ |
| 일반 운영자 | ✅ | ✅ | ✅ | ❌ |
| 시니어 운영자 | ✅ | ✅ | ✅ | ✅ |
| 관리자 | ✅ | ✅ | ✅ | ✅ |
💡 권장: 신규 입사자는 처음 1~2주간 Development만 접근하도록 설정하여 실수를 방지하세요.
환경을 직접 추가, 수정, 삭제할 수 있습니다.
경로: 설정 (Settings) → 환경 관리 (Environment Management)
필요 권한: environments.manage
| 컬럼 | 설명 |
|---|---|
| 환경 이름 | 시스템 내부 식별자 (예: development, production) |
| 표시 이름 | 대시보드에 표시되는 이름 |
| 환경 타입 | Development / Staging / Production |
| 설명 | 환경에 대한 부가 설명 |
| 기본 환경 | 새 사용자의 기본 접속 환경 |
| 시스템 정의 | 시스템에서 자동 생성한 환경 여부 |
| 승인 필요 | 변경 시 승인 프로세스 필요 여부 |
| 표시 | 환경 선택기에 표시 여부 |
| 작업 | ✏️ 편집, 🗑️ 삭제 버튼 |
[환경 추가] 버튼을 클릭하여 새 환경을 생성합니다.
| 항목 | 필수 | 설명 |
|---|---|---|
| 환경 이름 | ✅ | 시스템 내부 식별자 (영문, 소문자, 언더스코어만 사용) |
| 표시 이름 | ✅ | 대시보드에 표시될 이름 |
| 환경 타입 | ✅ | Development / Staging / Production 중 선택 |
| 설명 | 환경 용도에 대한 설명 | |
| 베이스 환경 | 기존 환경의 데이터를 복사할 경우 선택 | |
| 승인 필요 설정 | 이 환경에서 변경 시 승인 절차 필요 여부 |
💡 베이스 환경 기능: 새 환경 생성 시 기존 환경을 선택하면, 해당 환경의 데이터(월드, 세그먼트, 템플릿 등)가 복사됩니다.
목록에서 [✏️ 편집] 버튼을 클릭하여 환경 설정을 수정합니다.
| 항목 | 설명 |
|---|---|
| 환경 이름 | 변경 불가 (시스템 식별자) |
| 표시 이름 | 대시보드 표시명 변경 가능 |
| 설명 | 환경 설명 변경 |
| 환경 타입 | Development / Staging / Production 변경 |
| 색상 | 환경 구분용 색상 코드 (예: #4CAF50) |
| 승인 필요 설정 | 승인 프로세스 활성화/비활성화 |
⚠️ 주의: Production 환경의 설정을 변경할 때는 신중하게 진행하세요.
목록에서 [🗑️ 삭제] 버튼을 클릭하여 환경을 삭제합니다.
⚠️ 경고: 환경을 삭제하면 해당 환경의 모든 데이터(클라이언트 버전, 공지사항, 쿠폰 등)가 영구 삭제됩니다! 복구할 수 없습니다.
삭제 전 확인 사항:
- [ ] 해당 환경에 중요 데이터가 없는지 확인
- [ ] 백업이 필요한 데이터는 미리 내보내기
- [ ] 다른 팀원에게 삭제 사실 공유
기존 환경의 데이터를 포함한 새 환경을 빠르게 생성할 수 있습니다.
Q: 환경을 새로 추가하려면 어떻게 하나요?
A: 설정 → 환경 관리에서 [환경 추가] 버튼을 클릭하여 새 환경을 생성할 수 있습니다. environments.manage 권한이 필요합니다.
Q: 실수로 Production에 테스트 데이터를 넣었어요!
A: 즉시 해당 데이터를 비활성화하거나 삭제하세요. 그리고 감사 로그에서 영향 범위를 확인하고 팀에 공유하세요.
Q: Dev에서 작업한 내용을 Prod에 일괄 적용할 수 있나요?
A: 현재는 자동 동기화 기능이 없습니다. 각 환경에서 개별적으로 등록해야 합니다. 단, 새 환경 생성 시 베이스 환경을 선택하면 데이터를 복사할 수 있습니다.
Q: 환경 삭제 시 데이터가 복구 가능한가요?
A: 아니요, 환경 삭제 시 해당 환경의 모든 데이터가 영구 삭제됩니다. 삭제 전 반드시 백업하세요.
Q: "승인 필요" 설정은 무엇인가요?
A: 이 설정을 활성화하면, 해당 환경에서 데이터 변경 시 상위 관리자의 승인이 필요합니다. Production 환경에 권장되는 설정입니다.
이전 장: ← 제 2장: 대시보드 개요
다음 장: 제 3장: 사용자 관리 →
사용자 관리는 대시보드에 접속할 수 있는 운영자 계정을 관리하고 권한을 제어하는 기능입니다. 이 챕터에서는 단순한 기능 설명을 넘어, 입사/퇴사 등 실제 업무 상황에서의 처리 절차를 안내합니다.
경로: 관리 (Admin) → 사용자 (Users)
필요 권한: users.manage (수정 시), users.view (조회 시)
🎬 영상 가이드: 사용자 관리 방법 보기
사용자 관리 페이지의 전체 화면입니다.
sequenceDiagram
participant Admin as 기존 관리자
participant System as Gatrix 시스템
participant User as 신규 사용자
Admin->>System: 1. 초대장 발송 (이메일 입력)
System->>User: 2. 초대 이메일 전송 (링크 포함)
User->>System: 3. 링크 클릭 및 회원가입 양식 작성
System->>User: 4. 가입 완료 및 로그인
| 버튼 | 설명 |
|---|---|
| 사용자 추가 | 이름, 이메일, 비밀번호를 직접 입력하여 계정을 즉시 생성합니다. |
| 새 초대 생성 | 이메일로 초대 링크를 발송합니다. 사용자가 직접 가입하도록 유도할 때 사용합니다. |
⚠️ 중요: SMTP 설정 필수
이메일 발송 기능(초대장 발송, 비밀번호 재설정 등)을 사용하려면 SMTP 서버 설정이 올바르게 되어 있어야 합니다.
SMTP가 설정되지 않은 경우 이메일이 발송되지 않으며, 이 기능을 사용할 수 없습니다.🔧 관리자 가이드: 상세 설정 방법은 부록 A: 시스템 설정 가이드를 참고하세요.
| 컬럼 | 설명 |
|---|---|
| 사용자 | 사용자 이름 (프로필 사진 포함) |
| 이메일 | 로그인에 사용하는 이메일 주소 |
| 이메일 인증 | 이메일 인증 완료 여부 |
| 역할 | 관리자(Admin) 또는 사용자(User) |
| 상태 | 활성(Active), 대기(Pending), 정지(Suspended) |
| 환경 접근 권한 | 접근 가능한 환경 목록 (Dev, Staging, Production 등) |
| 태그 | 분류용 태그 |
| 가입일 | 계정 생성 일시 |
| 마지막 로그인 | 최근 접속 일시 |
| 작업 | ✏️ 편집, 🗑️ 삭제 버튼 |
Gatrix의 권한 시스템은 역할(Role)과 세부 권한(Permissions)의 조합으로 이루어집니다.
사용자의 기본적인 등급을 결정합니다.
| 역할 | 설명 | 추천 대상 |
|---|---|---|
| User (사용자) | 기본 사용자. 조회(View) 기능 위주입니다. 데이터를 수정하거나 삭제할 수 없습니다. | 신규 입사자, 단순 모니터링 담당자, 타 부서 참관인 |
| Admin (관리자) | 관리자. 대부분의 수정(Edit) 권한을 가질 수 있습니다. | 게임 운영자, 사업 PM, QA 담당자, 개발자 |
Admin 역할이라도 모든 것을 할 수 있는 것은 아닙니다. 업무에 필요한 권한만 부여하세요.
주요 권한 목록:
| 권한 | 설명 | 추천 대상 |
|---|---|---|
users.manage |
동료 계정을 생성/수정/삭제 | 팀장급 |
game-worlds.manage |
서버 상태 변경 | 서버/인프라 담당 |
coupons.manage |
쿠폰 발행 | 사업/마케팅 담당 |
service-notices.manage |
공지사항 작성 | 운영자 |
audit-logs.view |
감사 로그 조회 | 보안 담당 |
maintenance.manage |
점검 관리 | 서버/인프라 담당 |
💡 원칙: "권한은 최소한으로 주고, 필요할 때 늘린다" (Principle of Least Privilege)
관리자가 직접 계정을 생성합니다.
입력 항목:
| 항목 | 필수 | 설명 |
|---|---|---|
| 이름 | ✅ | 사용자의 표시 이름 |
| 이메일 | ✅ | 로그인에 사용할 이메일 주소 |
| 비밀번호 | ✅ | 8자 이상의 안전한 비밀번호 |
| 역할 | ✅ | 관리자(Admin) 또는 사용자(User) |
| 태그 | 분류용 태그 (복수 선택 가능) | |
| 권한 채널 | 세부 권한 설정 |
사용자가 직접 가입하도록 초대합니다.
입력 항목:
| 항목 | 필수 | 설명 |
|---|---|---|
| 이메일 | ✅ | 초대할 이메일 주소 (복수 입력 가능) |
| 만료 시간 | 초대 링크 유효 기간 (기본: 48시간) |
신규 GM '홍길동'님이 입사했습니다.
flowchart TD
A[신규 입사자] --> B{계정 생성 방식}
B -->|직접 생성| C[관리자가 생성]
B -->|초대 발송| D[초대 링크 발송]
C --> E[계정 활성화]
D --> F[사용자 가입]
F --> E
E --> L[업무 시작]
style A fill:#e3f2fd
style L fill:#c8e6c9
상세 절차:
gildong.hong@company.com 입력User 역할 부여 권장 (실수 방지)Pending → Active로 변경Admin으로 승격 및 필요한 세부 권한 추가특정 담당자만의 권한이 필요할 때 (예: 쿠폰 발행 권한이 김철수님에게만 있는데 휴가를 감)
flowchart LR
A[담당자 휴가] --> B[❌ 비밀번호 공유 절대 금지!]
A --> C[✅ 대행자 계정에 임시 권한 부여]
C --> D[휴가 복귀 후 권한 회수]
style B fill:#ffcdd2
style C fill:#c8e6c9
보안 사고 방지를 위해 퇴사 즉시 접근을 차단해야 합니다.
flowchart TD
A[퇴사 통보] --> B[사용자 목록에서 퇴사자 검색]
B --> C[상태를 'Suspended' 로 변경]
C --> D[즉시 로그아웃됨]
D --> E[모든 권한 체크박스 해제]
E --> F[1~3개월 후 계정 삭제]
style A fill:#ffcdd2
style C fill:#fff9c4
style F fill:#e0e0e0
G[⚠️ 주의: 바로 삭제하지 마세요!]
G --> H[삭제하면 Audit Log에서<br/>'알 수 없는 사용자'로 표시됨]
style G fill:#ffcdd2
상세 절차:
특정 사용자에게 특정 환경만 접근하도록 제한할 수 있습니다.
| 환경 | 설명 | 접근 허용 대상 |
|---|---|---|
| Development | 개발 환경 | 개발자, QA |
| Staging | 스테이징 환경 | QA, 운영자 |
| Production | 운영 환경 (실제 유저) | 승인된 운영자만 |
| Review | 스토어 심사용 환경 | 심사 담당자 |
| CBT | 클로즈드 베타 환경 | CBT 담당자 |
💡 팁: 신규 입사자는 먼저 Development 환경만 접근하도록 설정하고, 익숙해진 후 Production 접근 권한을 부여하세요.
Q: 초대 메일이 안 온다고 합니다.
A: 스팸 메일함을 먼저 확인해 주세요. 그래도 없다면, 초대 링크의 유효기간이 만료되었을 수 있습니다. 기존 초대를 삭제하고 다시 초대를 생성하여 링크를 직접 메신저로 전달해 주세요.
Q: 갑자기 "권한이 없습니다(403 Forbidden)"라고 뜹니다.
A: 다음을 확인하세요.
1. 관리자가 귀하의 권한 설정을 변경했을 수 있습니다.
2. 접속하려는 환경(Environment)에 대한 접근 권한이 없을 수도 있습니다.
3. 팀장님께 문의하세요.
Q: 실수로 동료 계정을 정지시켰습니다.
A: 당황하지 마세요. 목록에서 해당 사용자를 찾아 상태를 다시 Active로 변경하면 즉시 복구됩니다.
Q: 비밀번호를 5회 틀려서 잠겼다고 합니다.
A: 보안 정책상 잠긴 것입니다. 관리자 화면에서 해당 사용자의 편집 버튼을 클릭하고 [비밀번호 초기화 메일 발송]을 눌러주세요.
증상: 초대 링크를 발송했는데 메일을 받지 못함
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 스팸 메일함 | 스팸/정크 폴더 확인 |
| 메일 주소 오타 | 이메일 주소 정확히 입력했는지 확인 |
| 사내 메일 필터 | IT팀에 화이트리스트 요청 |
| 초대 유효기간 만료 | 새 초대 생성 후 직접 링크 공유 |
증상: 사용자가 비밀번호를 분실하여 로그인 불가
해결 방법:
1. 로그인 페이지 → "비밀번호 찾기" 클릭
2. 등록된 이메일로 재설정 링크 발송
3. 메일 확인 후 새 비밀번호 설정
관리자가 직접 재설정하려면:
1. 사용자 관리 → 해당 사용자 편집
2. [비밀번호 초기화 메일 발송] 클릭
증상: 특정 메뉴나 기능에 접근 시 "권한이 없습니다" 오류
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 해당 권한 미부여 | 관리자에게 권한 요청 |
| 환경 접근 권한 없음 | 해당 환경 접근 권한 추가 |
| 세션 만료 | 로그아웃 후 재로그인 |
| 역할(Role) 부족 | User → Admin 승격 필요 |
클릭하여 새 창에서 재생하세요.
이전 장: ← 제 2장: 대시보드 개요
다음 장: 제 4장: 클라이언트 버전 관리 →
앱 업데이트 시 가장 핵심이 되는 기능입니다. 사용자의 앱 버전과 서버의 허용 버전을 매칭하여 "업데이트를 받을지", "게임을 계속할지"를 결정합니다.
경로: 관리 (Admin) → 클라이언트 버전 (Client Versions)
필요 권한: client-versions.manage
🎬 영상 가이드: 클라이언트 버전 관리 방법 보기
클라이언트 버전 관리 페이지의 전체 화면입니다.
화면 상단에는 다음과 같은 버튼들이 있습니다:
| 번호 | 버튼 | 설명 |
|---|---|---|
| ① | 내보내기 | 현재 버전 리스트를 CSV/Excel 파일로 내보냅니다. 백업이나 외부 공유 시 유용합니다. |
| ② | 개별 추가 | 서버 주소, 화이트리스트 설정 등 모든 항목을 직접 지정하여 새 버전을 추가합니다. |
| ③ | 간편 추가 | 버전과 플랫폼만 입력하면 나머지는 기본값을 사용합니다. 빠른 등록에 적합합니다. |
| ④ | SDK 연동 가이드 | 클라이언트 개발자를 위한 API 문서와 테스트 도구를 제공합니다. |
| 컬럼 | 설명 |
|---|---|
| 클라이언트 버전 | SemVer 형식의 버전 번호 (예: 1.0.0, 2.1.3) |
| 플랫폼 | PC, iOS, Android, HarmonyOS 등 클라이언트 플랫폼 |
| 클라이언트 상태 | 업데이트 정책 상태 (온라인, 강제 업데이트 등) |
| 게임 서버 주소 | 게임 로직 서버 URL |
| 패치 주소 | CDN 또는 패치 다운로드 URL |
| 게스트 모드 허용 | 비로그인 상태로 게임 가능 여부 |
| 태그 | 분류용 태그 (필터링에 활용) |
| 생성일시 | 버전 등록 일시 |
| 생성자 | 버전을 등록한 관리자 |
| 작업 | 🔄 복사, ✏️ 편집, 🗑️ 삭제 버튼 |
상태를 잘못 설정하면 유저가 게임에 접속하지 못하거나, 심각한 버그가 있는 버전으로 계속 게임을 하게 됩니다.
| 상태 | 아이콘 | 화면 예시 | 언제 쓰나요? |
|---|---|---|---|
| 온라인 | 🟢 | (아무 팝업 없음) | 현재 문제가 없는 정상 버전일 때 |
| 오프라인 | ⚫ | "서비스가 종료되었습니다." | 서비스 중단 상태 |
| 권장 업데이트 | 🔵 | "새로운 기능이 추가되었습니다. [나중에] [업데이트]" | 마이너 버그 수정, 편의성 개선 등 |
| 강제 업데이트 | 🟠 | "필수 업데이트가 필요합니다. [확인]" | 시즌 시작, 치명적 버그 수정 시 |
| 리뷰 중 | 🟡 | (심사팀 전용 접속) | 스토어 심사 중인 버전 |
| 접속불가&패치허용 | 🟣 | "점검 중이지만 패치를 받을 수 있습니다." | 게임은 막고 패치만 허용 |
| 점검중 | 🔴 | "현재 점검 중입니다." | 특정 버전 차단 필요 시 |
⚠️ 주의: 운영 환경(Production)에서 상태를 변경하면 즉시 실제 유저에게 반영됩니다. 변경 전 반드시 테스트 환경에서 검증하세요.
[개별 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.
| 섹션 | 항목 | 필수 | 설명 |
|---|---|---|---|
| 기본 정보 | 버전 | ✅ | SemVer 형식으로 입력 (예: 1.0.0, 2.1.3-beta.1) |
| 플랫폼 | ✅ | PC, iOS, Android, HarmonyOS 등 선택 | |
| 상태 라벨 | ✅ | 위 상태 중 선택 (기본값: 온라인) | |
| 서버 주소 | 게임 서버 주소 | ✅ | 게임 로직 서버 URL (예: https://game.example.com) |
| 화이트리스트용 게임 서버 주소 | 테스터/심사팀용 별도 서버 URL | ||
| 패치 주소 | CDN 또는 패치 서버 URL | ||
| 화이트리스트용 패치 주소 | 테스터/심사팀용 별도 패치 URL | ||
| 기타 | 태그 | 분류용 태그 (복수 선택 가능) | |
| 게스트 모드 허용 | 비로그인 플레이 허용 여부 |
특정 계정 ID 또는 IP 주소를 화이트리스트에 등록하면, 해당 사용자는 일반 서버 대신 화이트리스트용 서버 주소로 연결됩니다.
활용 예시:
- 스토어 심사팀이 새 버전을 테스트할 때 (심사 계정 ID 등록)
- 내부 QA팀이 개발 서버에서 테스트할 때 (사내 IP 등록)
- 베타 테스터에게 별도 서버 제공 시
빠르게 버전만 등록하고 싶을 때 사용합니다.
팁: 기본값을 잘 설정해 두면 간편 추가로 수초 내에 버전 등록이 가능합니다.
각 플랫폼에 대해 공통으로 사용할 기본 서버 주소를 미리 설정합니다.
설정 항목:
- 게임 서버 주소 (기본값)
- 패치 주소 (기본값)
- 화이트리스트용 서버 주소 (기본값)
설정된 기본값은 간편 추가 시 자동으로 적용됩니다.
클라이언트에서 버전 정보를 조회할 수 있는 API를 제공합니다.
[SDK 연동 가이드] 버튼을 클릭하면 아래와 같은 화면이 나타납니다.
| 항목 | 설명 |
|---|---|
| 엔드포인트 | GET /api/v1/client/{environment}/client-version |
| 파라미터 | platform (필수), version (필수), lang (선택) |
| 필수 헤더 | X-Application-Name, X-API-Token, Content-Type |
| curl 예시 | 복사하여 터미널에서 바로 테스트 가능 |
실제 API를 호출해 볼 수 있는 테스트 도구입니다.
활용 팁: 버전 등록 후 API 테스트 탭에서 올바르게 응답되는지 반드시 확인하세요.
신규 버전 1.2.0을 배포하는 상황을 가정해 봅시다.
┌─────────────────────────────────────────────────────────────┐
│ 업데이트 배포 프로세스 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1단계: 스토어 출시 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 구글/애플 스토어에 1.2.0 앱 제출 → 심사 통과 → 출시 │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↓ │
│ 2단계: Gatrix에 신규 버전 등록 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 버전: 1.2.0 / 상태: 온라인 │ │
│ │ (기존 1.1.0도 온라인 유지 → 자연스러운 업데이트 유도) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↓ │
│ 3단계: 강제 업데이트 전환 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1.1.0 상태 → 강제 업데이트로 변경 │ │
│ │ (구버전 유저는 스토어로 이동됨) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
1단계: 마켓에 앱 제출 및 출시 확인
2단계: Gatrix에 새 버전 등록
1. [개별 추가] 또는 [간편 추가] 클릭
2. 버전: 1.2.0, 상태: 온라인
3. [저장]
4. API 테스트로 정상 응답 확인
3단계: 구버전 강제 업데이트 설정
1. 1.1.0 편집 버튼 클릭
2. 상태를 강제 업데이트로 변경
3. [저장]
┌─────────────────────────────────────────────────────────────┐
│ 긴급 롤백 프로세스 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 1.2.0 버전 상태 → 점검중 또는 오프라인으로 변경 │
│ ↓ │
│ 2. 1.1.0 (구버전) 상태 → 온라인으로 복구 │
│ ↓ │
│ 3. 공지사항 등록: "구버전 재설치 안내" │
│ │
└─────────────────────────────────────────────────────────────┘
대응 메시지 예시:
"버전 1.2.0에서 발견된 오류로 인해 임시로 서비스를 중단합니다. 앱 스토어에서 이전 버전을 재설치해 주시기 바랍니다."
업데이트 배포 전 반드시 확인하세요.
Q: 버전을 등록했는데 클라이언트에서 조회가 안 됩니다.
A: 다음을 순서대로 확인하세요.
1. 환경(Environment) 선택이 올바른가요? (상단 헤더 확인)
2. 플랫폼이 정확한가요? (PC, ios, android 등)
3. SDK 가이드 → API 테스트에서 해당 버전을 조회해 보세요.
4. API 토큰이 유효한가요?
Q: 화이트리스트용 서버 주소는 언제 사용되나요?
A: 화이트리스트에 등록된 계정 ID 또는 IP 주소로 접속하면 화이트리스트용 서버 주소가 반환됩니다.
활용 사례:
- 스토어 심사팀 테스트 (심사 계정 ID 등록)
- 내부 QA팀 개발 서버 접속 (사내 IP 등록)
- 베타 테스터 전용 서버 제공 (테스터 계정 ID 등록)
Q: 간편 추가와 개별 추가의 차이는 무엇인가요?
| 구분 | 간편 추가 | 개별 추가 |
|---|---|---|
| 입력 항목 | 버전, 플랫폼 | 모든 항목 |
| 서버 주소 | 플랫폼별 기본값 사용 | 직접 입력 |
| 화이트리스트 | 기본값 사용 | 직접 설정 가능 |
| 적합한 경우 | 빠른 등록 | 상세 커스터마이징 |
Q: 버전 복사 기능은 무엇인가요?
A: 기존 버전의 모든 설정을 복사하여 새 버전을 생성합니다. 버전 번호만 변경하면 되어 반복 작업 시 편리합니다.
증상: API 테스트에서도 버전 정보가 조회되지 않음
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 환경(Environment) 불일치 | 올바른 환경에 등록했는지 확인 |
| 플랫폼 불일치 | ios, android, pc 등 정확한 플랫폼 확인 |
| 버전 형식 오류 | SemVer 형식(1.0.0) 준수 확인 |
| API 토큰 문제 | 유효한 토큰인지 확인 |
증상: 구버전을 강제 업데이트로 설정했는데 유저에게 팝업 미표시
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 클라이언트 SDK 미구현 | 개발팀에 버전 체크 로직 확인 요청 |
| 스토어 URL 미설정 | 업데이트 버튼 클릭 시 이동할 URL 설정 |
| 캐싱 문제 | 앱 완전 종료 후 재시작, 5분 대기 |
| 잘못된 버전 선택 | 현재 유저가 사용하는 정확한 버전 확인 |
증상: 앱스토어/구글플레이 심사팀이 게임 접속 불가
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 리뷰 버전 미등록 | Review 환경에 해당 버전 등록 |
| 상태가 "리뷰 중" 아님 | 상태를 "리뷰 중"으로 변경 |
| 화이트리스트 누락 | 심사 계정 ID를 화이트리스트에 추가 |
| 서버 주소 오류 | 화이트리스트용 서버 주소 확인 |
클릭하여 새 창에서 재생하세요.
이전 장: ← 제 3장: 사용자 관리
다음 장: 제 5장: 게임 월드 관리 →
게임의 월드(서버) 목록을 관리하고 점검 상태를 제어하는 기능입니다. 유저가 게임에 접속할 때 보게 되는 서버 목록이 여기서 관리됩니다.
경로: 관리 (Admin) → 게임 월드 (Game Worlds)
필요 권한: game-worlds.manage
🎬 영상 가이드: 게임 월드 관리 방법 보기
게임 월드 관리 페이지의 전체 화면입니다.
| 버튼 | 설명 |
|---|---|
| 게임 월드 추가 | 새로운 게임 월드(서버)를 등록합니다. |
| SDK 연동 가이드 | 클라이언트에서 월드 목록을 조회하는 API 문서를 제공합니다. |
| 컬럼 | 설명 |
|---|---|
| 월드 ID | 시스템에서 사용하는 고유 식별자 (예: UWO-RELCN-01) |
| 이름 | 유저에게 표시되는 월드 이름 |
| 설명 | 월드에 대한 부가 설명 |
| 월드 서버 주소 | 게임 로직 서버 URL |
| 표시 여부 | 유저에게 월드 목록에 노출될지 여부 |
| 점검 여부 | 현재 점검 중인지 여부 |
| 태그 | 분류용 태그 |
| 생성일 | 월드 등록 일시 |
| 생성자 | 월드를 등록한 관리자 |
| 작업 | 📋 복사, ✏️ 편집, 🗑️ 삭제 버튼 |
월드는 다음 상태들을 가질 수 있습니다.
stateDiagram-v2
[*] --> Normal: 월드 생성
Normal --> Maintenance: 점검 시작
Maintenance --> Normal: 점검 종료
Normal --> Hidden: 숨김 처리
Hidden --> Normal: 표시 전환
state Normal {
[*] --> Visible
Visible: 🟢 유저에게 표시
}
state Maintenance {
[*] --> InProgress
InProgress: 🔴 점검 중
note right of InProgress: 유저 접속 차단
}
state Hidden {
[*] --> Invisible
Invisible: ⚪ 숨김 상태
}
| 상태 | 아이콘 | 설명 |
|---|---|---|
| 표시 (Visible) | 🟢 | 유저에게 월드 목록에 노출됩니다. |
| 숨김 (Hidden) | ⚪ | 유저에게 보이지 않습니다. 개발 중인 월드에 적합합니다. |
| 정상 (Normal) | 🟢 | 유저 접속이 가능한 상태입니다. |
| 점검 중 (Maintenance) | 🔴 | 점검 중인 상태로, 유저 접속이 차단됩니다. |
[게임 월드 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.
| 항목 | 필수 | 설명 |
|---|---|---|
| 월드 ID | ✅ | 고유한 월드 식별자 (예: UWO-RELCN-01) |
| 이름 | ✅ | 유저에게 표시되는 월드 이름 |
| 설명 | 월드에 대한 부가 설명 | |
| 월드 서버 주소 | ✅ | 게임 로직 서버 URL (예: 127.0.0.1:10000) |
| 태그 | 분류용 태그 | |
| 사용자에게 표시 | 이 월드를 유저에게 표시할지 여부 | |
| 점검 중 | 점검 모드 설정 시 체크 | |
| 커스텀 페이로드 | JSON 형식의 추가 데이터 (클라이언트에 전달됨) |
고급 서버 및 인프라 설정을 JSON 형식으로 관리할 수 있습니다.
월드별로 점검 상태를 설정하여 유저 접속을 제어할 수 있습니다.
flowchart TD
A[점검 모드 활성화] --> B{강제 접속 종료?}
B -->|예| C[유예 시간 경고 표시]
B -->|아니오| D[새 접속만 차단]
C --> E[유예 시간 경과]
E --> F[접속 중인 유저 강제 종료]
D --> G[기존 유저는 계속 플레이 가능]
F --> H[점검 완료까지 대기]
G --> H
H --> I[점검 종료 - 접속 재개]
style A fill:#ffcdd2
style I fill:#c8e6c9
| 항목 | 설명 |
|---|---|
| 점검 기간 | 점검 시작 시간과 종료 시간 |
| 점검 메시지 | 유저 접속 시도 시 표시할 안내 메시지 |
| 다국어 지원 | 한국어, 영어, 중국어 등 언어별 메시지 설정 |
| 강제 접속 종료 | 점검 시작 시 접속 중인 유저 강제 퇴장 여부 |
| 유예 시간 | 강제 종료 전 경고 메시지 표시 시간 (분) |
월드 목록에서 드래그 핸들을 이용하여 월드의 노출 순서를 변경할 수 있습니다.
💡 팁: 신규 월드나 이벤트 월드를 상단에 배치하여 유저의 관심을 유도할 수 있습니다.
클라이언트에서 월드 목록을 조회할 수 있는 API를 제공합니다.
GET /api/v1/client/{environment}/game-worlds
SDK 가이드의 API 테스트 탭에서 직접 API를 호출하여 응답을 확인할 수 있습니다.
flowchart LR
A[월드 생성<br/>숨김 상태] --> B[테스트 및<br/>QA 진행]
B --> C[공지사항<br/>작성]
C --> D[오픈 시간에<br/>표시 전환]
D --> E[모니터링]
style A fill:#e3f2fd
style D fill:#c8e6c9
flowchart TD
A[서버 장애 발생] --> B[월드 편집<br/>점검 중 활성화]
B --> C[강제 접속 종료<br/>설정]
C --> D[점검 메시지<br/>입력]
D --> E[공지사항<br/>등록]
E --> F[문제 해결]
F --> G[점검 종료<br/>접속 재개]
style A fill:#ffcdd2
style G fill:#c8e6c9
Q: 월드를 숨겼는데 기존 접속자는 어떻게 되나요?
A: "사용자에게 표시" 옵션은 목록 노출만 제어합니다. 이미 접속 중인 유저는 영향을 받지 않습니다. 접속을 차단하려면 "점검 중" 옵션을 사용하세요.
Q: 점검 시간을 예약할 수 있나요?
A: 현재 버전에서는 수동으로 점검 모드를 전환해야 합니다. 예약 기능이 필요하면 전체 점검 관리 메뉴를 활용하세요.
Q: 커스텀 페이로드는 어떻게 사용하나요?
A: JSON 형식으로 추가 데이터를 입력하면, 클라이언트에서 월드 목록 조회 시 함께 전달됩니다. 예: {"event": "summer_festival", "maxPlayers": 5000}
증상: 대시보드에서 월드를 등록했으나 게임 내 서버 목록에 표시되지 않음
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| "사용자에게 표시" 비활성화 | 토글 상태 확인 |
| 환경 불일치 | Production 환경에 등록했는지 확인 |
| 점검 중 상태 | 점검 중이면 숨김 처리될 수 있음 |
| 캐싱 문제 | 앱 재시작 또는 5분 대기 |
증상: 드래그로 순서를 변경했는데 저장 후에도 반영되지 않음
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 저장 버튼 미클릭 | 순서 변경 후 [저장] 클릭 필수 |
| 새로고침 없이 확인 | 페이지 새로고침 후 재확인 |
| 권한 부족 | game-worlds.manage 권한 확인 |
클릭하여 새 창에서 재생하세요.
이전 장: ← 제 4장: 클라이언트 버전 관리
다음 장: 제 6장: 점검 관리 →
점검은 유저들에게 가장 큰 불편을 주는 작업이므로, 정확한 시간 안내와 안정적인 종료가 생명입니다.
🎬 영상 가이드: 점검 관리 방법 보기
Gatrix는 3단계 점검 체계를 제공합니다. 각 단계별로 점검 범위가 다르며, 상황에 맞게 적절한 점검 방식을 선택해야 합니다.
flowchart TB
subgraph 서비스["🌐 서비스 전체 점검"]
A[모든 유저 접속 차단<br/>최상위 우선순위]
end
subgraph 클라이언트["📱 클라이언트 버전별 점검"]
B[특정 버전만 차단<br/>API 조회 방식]
end
subgraph 월드["🗺️ 월드별 점검"]
C[특정 월드만 점검<br/>다른 월드는 정상 운영]
end
A --> B
B --> C
style A fill:#ffcdd2
style B fill:#fff9c4
style C fill:#e3f2fd
flowchart TD
A[유저 접속 시도] --> B{서비스 전체<br/>점검 중?}
B -->|예| C[❌ 접속 차단<br/>점검 안내]
B -->|아니오| D{해당 클라이언트<br/>버전 점검 중?}
D -->|예| E[❌ 접속 차단<br/>버전별 점검 안내]
D -->|아니오| F{접속할 월드<br/>점검 중?}
F -->|예| G[❌ 해당 월드만<br/>접속 불가]
F -->|아니오| H[✅ 정상 접속]
style C fill:#ffcdd2
style E fill:#ffcdd2
style G fill:#fff9c4
style H fill:#c8e6c9
모든 유저의 접속을 차단하는 최상위 점검입니다. 서버 업데이트, DB 마이그레이션 등 전체 서비스에 영향을 주는 작업 시 사용합니다.
경로: 관리자 패널 → 서비스 제어 → 서비스 점검
필요 권한: maintenance.manage
| 항목 | 설명 |
|---|---|
| 점검 상태 | 현재 점검 활성화 여부 |
| 시작 시간 | 점검 시작 일시 (비워두면 즉시 시작) |
| 종료 시간 | 점검 종료 일시 (비워두면 수동 종료) |
| 기존 플레이어 강제 종료 | 점검 시작 시 접속 중인 유저 강제 퇴장 |
| 점검 메시지 | 유저에게 표시할 안내 메시지 |
| 다국어 메시지 | 언어별로 다른 메시지 설정 가능 |
flowchart LR
A[서비스 점검 시작] --> B[모든 유저 접속 차단]
B --> C[실시간 적용]
C --> D[화이트리스트만<br/>접속 가능]
style A fill:#ffcdd2
style D fill:#c8e6c9
점검이 시작되어도 이미 접속 중인 플레이어는 즉시 차단되지 않습니다.
| 설정 | 동작 |
|---|---|
| 강제 종료: OFF | 기존 플레이어는 계속 플레이 가능. 단, 게임 화면 우측 상단에 점검 중임을 알리는 작은 배너가 표시됩니다. |
| 강제 종료: ON | 점검 시작 시 접속 중인 모든 유저를 강제 퇴장시킵니다. 설정에 따라 즉시 또는 일정 시간(예: 5분) 후 킥됩니다. 킥 전 게임 내에서 안내 메시지가 표시됩니다. |
💡 게임 내 점검 배너: 점검 중에도 플레이할 수 있는 유저들에게는 화면 우측 상단 아래에 "점검 중" 배너가 나타나, 서비스 상태를 인지할 수 있도록 안내합니다. 점검 종료 후 배너는 자동으로 사라집니다.
특정 클라이언트 버전만 점검 상태로 전환합니다. API 조회 방식으로 동작하며, 클라이언트가 버전 체크 API를 호출할 때 점검 상태를 반환합니다.
경로: 관리자 패널 → 클라이언트 버전 → 버전 편집
필요 권한: client-versions.manage
🎬 영상 가이드: 클라이언트 버전 관리 보기
sequenceDiagram
participant C as 게임 클라이언트
participant E as Edge API
participant G as Gatrix
C->>E: 버전 체크 요청 (v2.1.0)
E->>G: 버전 상태 조회
G-->>E: 상태: MAINTENANCE
E-->>C: 점검 중 응답 + 메시지
C->>C: 점검 안내 화면 표시
주요 특징:
- 클라이언트가 버전 체크 API를 호출할 때 점검 상태를 확인합니다.
- 이미 접속 중인 유저에게는 즉시 반영되지 않습니다.
- 신규 접속자 또는 재접속 시에만 점검이 적용됩니다.
| 상황 | 설명 |
|---|---|
| 구버전 점검 | 강제 업데이트 전 구버전 유저 차단 |
| 신버전 테스트 | 신버전을 점검 상태로 두고 화이트리스트로 테스트 |
| 롤백 대비 | 문제 발생 시 특정 버전만 빠르게 차단 |
특정 게임 월드(서버)만 점검 상태로 전환합니다. 다른 월드는 정상 운영됩니다.
경로: 관리자 패널 → 게임 월드 → 월드 편집
필요 권한: game-worlds.manage
🎬 영상 가이드: 게임 월드 관리 보기
flowchart TD
subgraph 서버목록["서버 선택 화면"]
A["🟢 월드A (정상)"]
B["🔴 월드B (점검 중)"]
C["🟢 월드C (정상)"]
end
A --> D[접속 가능]
B --> E[접속 차단<br/>점검 안내]
C --> D
style B fill:#ffcdd2
style D fill:#c8e6c9
style E fill:#ffcdd2
| 상황 | 설명 |
|---|---|
| 월드별 업데이트 | 특정 월드만 데이터 마이그레이션 |
| 부하 분산 | 과부하 월드 임시 점검 |
| 이벤트 준비 | 이벤트 월드 사전 세팅 |
Gatrix의 점검은 적용 방식에 따라 두 가지로 나뉩니다.
| 구분 | 실시간 적용 | API 조회 적용 |
|---|---|---|
| 서비스 전체 점검 | ✅ | |
| 클라이언트 버전 점검 | ✅ | |
| 월드별 점검 | ✅ | |
| 기존 접속자 | 즉시 적용 | 재접속 시 적용 |
| 적용 시점 | 설정 즉시 | API 호출 시 |
flowchart LR
A[점검 설정 저장] --> B[서버에서<br/>접속 확인]
B --> C[즉시 차단/<br/>허용 결정]
style C fill:#c8e6c9
flowchart LR
A[클라이언트 실행] --> B[버전 체크<br/>API 호출]
B --> C[점검 상태<br/>응답 받음]
C --> D[점검 화면<br/>표시]
style D fill:#fff9c4
점검 중에도 QA팀, 개발팀, 마켓 검수팀이 접속할 수 있도록 예외를 설정합니다.
경로: 관리자 패널 → 화이트리스트
필요 권한: whitelist.manage
🎬 영상 가이드: 화이트리스트 관리 보기
| 유형 | 설명 | 사용 사례 |
|---|---|---|
| 계정 ID (Account ID) | 특정 유저 계정만 허용 | QA 테스터 개인 계정, 마켓 검수 계정 |
| IP 주소 | 특정 IP에서의 접속 허용 | 사내 네트워크, 개발실 IP |
⚠️ 참고: Device ID는 화이트리스트 조건으로 사용하지 않습니다. 계정 ID와 IP 주소만 체크합니다.
flowchart TD
A[접속 시도] --> B{점검 중?}
B -->|아니오| C[✅ 접속 허용]
B -->|예| D{계정 ID<br/>화이트리스트?}
D -->|예| C
D -->|아니오| E{IP 주소<br/>화이트리스트?}
E -->|예| C
E -->|아니오| F[❌ 접속 차단]
style C fill:#c8e6c9
style F fill:#ffcdd2
| 대상 | 추천 유형 | 이유 |
|---|---|---|
| 애플/구글 검수팀 | 계정 ID | 검수팀 IP 알 수 없음 |
| 사내 전체 | IP 주소 | 일괄 허용 편리 |
| 재택 근무자 | 계정 ID | IP 변경 가능성 |
| 외부 QA 업체 | 계정 ID | 보안상 계정 단위 관리 |
flowchart TD
A[신버전 배포] --> B[구버전 상태를<br/>'점검 중'으로 변경]
B --> C[구버전 유저:<br/>업데이트 안내]
C --> D[신버전으로<br/>업데이트]
style D fill:#c8e6c9
D-1일 (전일)
- [ ] 서비스 점검 예약 설정
- [ ] 시작/종료 시간 정확히 입력
- [ ] 사전 공지사항 게시
- [ ] QA/검수 계정 화이트리스트 등록
D-Day
- [ ] 30분 전 인게임 알림 발송
- [ ] 점검 시작 확인
- [ ] QA 테스트 완료
- [ ] 점검 종료 및 서버 오픈 확인
- [ ] 점검 완료 공지사항 게시
Q: 버전별 점검을 설정했는데 기존 유저가 계속 플레이하고 있어요.
A: 클라이언트 버전별 점검은 API 조회 방식입니다. 이미 접속 중인 유저에게는 적용되지 않으며, 재접속 시에만 점검 상태가 반영됩니다.
Q: 화이트리스트에 Device ID를 등록할 수 있나요?
A: 아니요, 현재 화이트리스트는 계정 ID와 IP 주소만 지원합니다. Device ID는 사용하지 않습니다.
Q: 서비스 점검 중에 월드별 점검을 따로 설정해야 하나요?
A: 아니요, 서비스 전체 점검이 최상위 우선순위이므로 모든 월드가 자동으로 차단됩니다.
Q: 점검 시간을 연장하려면?
A: 서비스 점검 화면에서 종료 시간을 수정하고 저장하면 됩니다. 연장 시 최소 30분 전에 공지를 갱신하세요.
증상: 서비스 점검을 시작했는데 일부 유저가 여전히 게임 중
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| "기존 플레이어 강제 종료" 비활성화 | 해당 옵션 활성화 후 재저장 |
| 화이트리스트에 등록된 계정/IP | 화이트리스트 목록 확인 |
| 잘못된 환경에서 점검 설정 | 환경 선택기 확인 (Production인지) |
| 클라이언트 버전 점검만 설정 | 서비스 전체 점검으로 변경 |
증상: 점검 종료를 했는데 유저가 여전히 접속 불가
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 월드별 점검이 별도로 남아있음 | 게임 월드에서 점검 해제 |
| 클라이언트 버전 상태가 점검 중 | 클라이언트 버전 상태 확인 |
| 게임 서버 자체가 미기동 | 인프라팀에 서버 상태 확인 요청 |
| 캐시/CDN 문제 | 5분 대기 후 재확인 |
증상: 화이트리스트에 등록한 계정/IP인데 점검 안내가 표시됨
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 계정 ID 오타 | UUID 정확히 복사했는지 확인 |
| IP 주소 변경 | VPN 사용 시 IP 변경 가능, 계정 ID로 등록 |
| 환경 불일치 | 올바른 환경에 화이트리스트 등록했는지 확인 |
| 클라이언트 캐싱 | 앱 강제 종료 후 재시작 |
증상: 점검 시작 시간을 설정했는데 자동으로 시작되지 않음
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 시간대(Timezone) 불일치 | UTC vs KST 확인 |
| 과거 시간 입력 | 현재 시간 이후로 재설정 |
| 저장 안 함 | [저장] 버튼 눌렀는지 확인 |
| 백엔드 서버 문제 | 담당 개발팀 확인 요청 |
증상: 점검 안내 메시지에 HTML 태그가 그대로 보이거나 깨짐
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| HTML 태그 사용 | 점검 메시지는 Plain Text만 지원, 태그 제거 |
| 특수문자 문제 | <, >, & 등 특수문자 확인 |
| 인코딩 문제 | 복사/붙여넣기 대신 직접 입력 |
클릭하여 새 창에서 재생하세요.
클릭하여 새 창에서 재생하세요.
이전 장: ← 제 5장: 게임 월드 관리
다음 장: 제 7장: 공지사항 관리 →
게임 내 공지사항은 유저와의 가장 기본적인 소통 창구입니다. 점검 안내, 이벤트 홍보, 버그 수정 내역 등을 알릴 때 사용합니다.
경로: 게임 관리 (Game) → 서비스 공지 (Service Notices)
필요 권한: service-notices.manage
🎬 영상 가이드: 공지사항 관리 방법 보기
공지사항 관리 페이지의 전체 화면입니다.
flowchart LR
A[클라이언트 접속] --> B{점검 중인가?}
B -->|Yes| C[점검 공지 우선 노출]
B -->|No| D{활성 공지 있음?}
D -->|Yes| E[공지사항 노출]
D -->|No| F[공지 없음]
| 버튼 | 설명 |
|---|---|
| 미리보기 | 게임 내 웹뷰에서 공지사항이 어떻게 보이는지 미리 확인합니다. |
| 공지 추가 | 새로운 공지사항을 작성합니다. |
| 컬럼 | 설명 |
|---|---|
| 제목 | 공지사항 제목 |
| 📌 (상단 고정) | 상단 고정 여부 |
| 현재 표시 | 현재 유저에게 노출 중인지 여부 |
| 상태 | 활성(Active) / 비활성(Inactive) |
| 카테고리 | 점검, 이벤트, 공지, 프로모션, 기타 |
| 적용 대상 | 대상 플랫폼 및 채널 |
| 적용 기간 | 노출 시작~종료 일시 |
| 생성일 | 공지 작성 일시 |
| 수정일 | 최근 수정 일시 |
| 작업 | ✏️ 편집, 🗑️ 삭제 버튼 |
[공지 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.
| 섹션 | 항목 | 필수 | 설명 |
|---|---|---|---|
| 기본 설정 | 사용 여부 | ✅ | 토글 스위치로 활성화/비활성화 설정 |
| 대상 지정 | 대상 플랫폼 | 전체 또는 특정 플랫폼(iOS, Android, PC 등) 선택 | |
| 대상 채널 | 특정 서비스 채널 선택 | ||
| 노출 기간 | 시작일시 | 비워두면 즉시 게시 | |
| 종료일시 | 비워두면 영구 게시 | ||
| 표시 옵션 | 상단 고정 | 중요 공지를 목록 최상단에 고정 | |
| 분류 | 카테고리 | ✅ | 점검/이벤트/공지/프로모션/기타 |
| 태그 | 분류용 태그 | ||
| 내용 | 제목 | ✅ | 유저에게 표시되는 제목 |
| 내용 | ✅ | Rich Text Editor로 HTML 형식 작성 |
| 카테고리 | 용도 | 예시 |
|---|---|---|
| 점검 (Maintenance) | 점검 관련 안내 | "1/15 정기점검 안내" |
| 이벤트 (Event) | 게임 이벤트 홍보 | "설날 이벤트 안내" |
| 공지 (Notice) | 일반 공지사항 | "이용약관 변경 안내" |
| 프로모션 (Promotion) | 상품/결제 관련 | "신규 패키지 출시 안내" |
| 기타 (Other) | 그 외 안내 | "커뮤니티 가이드라인" |
Gatrix는 글로벌 서비스를 위해 다국어 공지 입력을 지원합니다.
특히 중국 서비스를 고려하여 간체/번체 입력을 올바르게 구분해야 합니다.
| 언어 | 코드 | 입력 예시 (제목) |
|---|---|---|
| 한국어 | ko-KR |
정기 점검 안내 |
| 영어 | en-US |
Scheduled Maintenance |
| 중국어(간체) | zh-CN |
定期维护通知 (중국 본토) |
| 중국어(번체) | zh-TW |
定期維護通知 (대만/홍콩) |
🌏 유의사항:
- 중국 서비스를 준비 중이라면 반드시 중국어(간체) 내용을 포함하세요.
- 번역된 내용이 없으면 기본 언어(한국어 또는 영어)로 표시될 수 있습니다.
공지사항 내용은 Rich Text Editor를 통해 HTML 형식으로 작성할 수 있습니다.
| 기능 | 설명 |
|---|---|
| 폰트 설정 | 폰트 종류 선택 (Noto Sans 등) |
| 크기 조절 | 텍스트 크기 조절 |
| 텍스트 스타일 | 굵게(B), 기울임(I), 밑줄(U) |
| 색상 설정 | 글자색, 배경색 변경 |
| 정렬 | 왼쪽, 가운데, 오른쪽 정렬 |
| 목록 | 번호 목록, 글머리 기호 목록 |
| 이미지 삽입 | 이미지 URL 또는 업로드 |
| 동영상 삽입 | YouTube 등 동영상 임베드 |
| 링크 삽입 | 외부 링크 추가 |
| 이모지 | 이모지 삽입 |
💡 팁: 모바일 화면에서의 가독성을 위해 복잡한 레이아웃은 피하고, 간결하게 작성하세요.
공지사항의 노출 상태는 여러 조건에 따라 결정됩니다.
flowchart TD
A[공지사항] --> B{사용 여부?}
B -->|비활성화| C[❌ 노출 안됨]
B -->|활성화| D{현재 시간?}
D -->|시작 전| E[⏳ 예약됨]
D -->|기간 내| F[✅ 현재 노출 중]
D -->|종료 후| G[⏹️ 종료됨]
style C fill:#ffcdd2
style E fill:#fff9c4
style F fill:#c8e6c9
style G fill:#e0e0e0
| 상태 | 아이콘 | 조건 |
|---|---|---|
| 현재 노출 중 | 🟢 | Active + 현재 시간이 기간 내 |
| 예약됨 | 🟡 | Active + 시작 시간이 미래 |
| 종료됨 | ⚪ | 종료 시간이 지남 |
| 비활성 | ⚫ | 사용 여부 비활성화 |
작성된 공지사항이 실제 게임 내 웹뷰에서 어떻게 보일지 미리 확인할 수 있습니다.
공지사항의 직접 링크가 필요할 때 사용합니다. (예: 커뮤니티에 링크 공유)
flowchart LR
A[D-1일] --> B[점검 공지 작성]
B --> C[시작일시: 즉시<br/>종료일시: 점검 종료 후]
C --> D[상단 고정 활성화]
D --> E[게시]
style A fill:#e3f2fd
style E fill:#c8e6c9
flowchart LR
A[이벤트 기획] --> B[공지 작성]
B --> C[시작일시: 이벤트 시작일<br/>종료일시: 이벤트 종료일]
C --> D[예약 상태로 대기]
D --> E[자동 게시]
style D fill:#fff9c4
style E fill:#c8e6c9
Q: 공지사항을 올렸는데 게임에서 안 보여요.
A: 다음을 순서대로 확인하세요.
1. 사용 여부가 활성화되어 있나요?
2. 현재 시간이 게시 기간(시작일시 ~ 종료일시) 사이인가요?
3. 플랫폼 설정이 올바른가요? (예: iOS로 접속했는데 타겟이 Android만 설정된 경우)
4. 환경(Environment) 선택이 올바른가요?
Q: HTML 태그를 쓸 수 있나요?
A: 네, 내용은 웹뷰를 통해 렌더링되므로 HTML 태그 사용이 가능합니다. Rich Text Editor에서 자동으로 HTML 코드가 생성됩니다.
Q: 이미지를 넣으려면 어떻게 하나요?
A: Rich Text Editor의 이미지 아이콘을 클릭하여 이미지 URL을 입력하거나 직접 업로드할 수 있습니다.
증상: 대시보드에서는 등록된 공지가 게임 내에서 표시되지 않음
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 사용 여부 비활성화 | "사용" 토글 상태 확인 |
| 기간 설정 오류 | 시작일시가 미래이거나 종료일시가 과거 |
| 플랫폼/채널 불일치 | 대상 설정이 해당 유저에게 적용되는지 확인 |
| 환경 불일치 | Production 환경에 등록했는지 확인 |
증상: 공지 내 이미지가 X 표시이거나 로딩 안됨
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 이미지 URL 오류 | URL을 브라우저에서 직접 열어 확인 |
| HTTP/HTTPS 혼용 | HTTPS URL 사용 권장 |
| CDN 접근 제한 | 이미지 호스팅 서비스 접근성 확인 |
| 이미지 삭제됨 | 원본 이미지 존재 여부 확인 |
증상: 다국어 공지에서 특정 언어만 표시됨
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 해당 언어 미입력 | 언어별 내용 모두 입력 확인 |
| 빈 문자열 저장 | 공백만 있는 경우도 비어 보임 |
| 기본 언어 Fallback | 기본 언어(한국어)만 입력 시 다른 언어에도 표시됨 확인 |
💡 단일 국가 서비스 시: 다국어 메시지 입력은 필요하지 않습니다. 기본 메시지만 입력하세요.
클릭하여 새 창에서 재생하세요.
이전 장: ← 제 6장: 점검 관리
다음 장: 제 8장: 인게임 팝업 관리 →
게임 접속 시 또는 특정 조건에서 자동으로 표시되는 팝업 공지입니다. 긴급 안내, 이벤트 홍보, 중요 정보 전달 등에 활용됩니다.
경로: 게임 관리 (Game) → 인게임 팝업 공지 (Ingame Popup Notices)
필요 권한: popup-notices.manage
🎬 영상 가이드: 인게임 팝업 관리 방법 보기
인게임 팝업 관리 페이지의 전체 화면입니다.
| 버튼 | 설명 |
|---|---|
| 팝업 공지 추가 | 새로운 팝업 공지를 작성합니다. |
| SDK 연동 가이드 | 클라이언트에서 팝업 공지를 조회하는 API 문서를 제공합니다. |
| 컬럼 | 설명 |
|---|---|
| 내용 | 팝업에 표시되는 메시지 내용 (미리보기) |
| 현재 표시 | 현재 유저에게 노출 중인지 여부 |
| 상태 | 활성(Active) / 비활성(Inactive) |
| 우선순위 | 노출 순서 (숫자가 작을수록 먼저 표시) |
| 대상 설정 | 대상 플랫폼 및 채널 |
| 적용 기간 | 노출 시작~종료 일시 |
| 생성일 | 팝업 생성 일시 |
| 작업 | ✏️ 편집, 🗑️ 삭제 버튼 |
[팝업 공지 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.
| 섹션 | 항목 | 필수 | 설명 |
|---|---|---|---|
| 기본 설정 | 사용 여부 | ✅ | 토글 스위치로 활성화/비활성화 설정 |
| 대상 지정 | 대상 플랫폼 | 전체 또는 특정 플랫폼 선택 | |
| 대상 채널 | 특정 서비스 채널 선택 | ||
| 노출 기간 | 시작일시 | 비워두면 즉시 표시 | |
| 종료일시 | 비워두면 영구 표시 | ||
| 노출 설정 | 우선순위 | 숫자가 작을수록 먼저 표시 (기본: 100) | |
| 한번만 노출 | 유저당 1회만 표시 (로그인/접속 시마다 표시하지 않음) | ||
| 템플릿 사용 | 메시지 템플릿에서 내용 불러오기 | ||
| 내용 | 내용 | ✅ | Plain Text 형식으로 팝업 메시지 입력 |
| 설명 | 관리용 메모 (유저에게 표시되지 않음) |
어떤 공지 방식을 사용해야 할지 헷갈린다면 아래 표를 참고하세요.
| 구분 | 인게임 팝업 | 서비스 공지 |
|---|---|---|
| 표시 방식 | 게임 내 팝업창 자동 표시 | 공지사항 메뉴 클릭 시 표시 |
| 노출 시점 | 게임 접속/로그인 시 자동 | 유저가 직접 확인 |
| 내용 형식 | Plain Text (간결하게) | Rich HTML (상세하게) |
| 적합한 용도 | 긴급 안내, 짧은 공지 | 상세한 이벤트 안내, 점검 상세 |
| 한번만 노출 | 지원 ✅ | 미지원 |
flowchart TD
A[공지할 내용] --> B{긴급도?}
B -->|높음: 즉시 알려야 함| C[인게임 팝업]
B -->|보통: 확인할 때 보면 됨| D[서비스 공지]
C --> E{내용 길이?}
E -->|짧음: 1-2문장| F[팝업만 사용]
E -->|길음: 상세 설명 필요| G[팝업 + 공지 둘 다]
style C fill:#ffcdd2
style D fill:#e3f2fd
여러 팝업이 동시에 활성화된 경우, 우선순위에 따라 표시 순서가 결정됩니다.
| 우선순위 | 표시 순서 | 권장 용도 |
|---|---|---|
| 1-10 | 먼저 표시 | 긴급 공지, 치명적 버그 안내 |
| 50-100 | 중간 | 일반 이벤트, 업데이트 안내 |
| 100-200 | 나중 표시 | 덜 중요한 안내, 광고 |
💡 팁: 우선순위는 "숫자가 작을수록 먼저 표시"됩니다. 긴급 공지는 우선순위 1-10을 사용하세요.
flowchart TD
A[로그인 성공] --> B[활성 팝업 목록 조회]
B --> C[우선순위 정렬 (내림차순)]
C --> D[1순위 팝업 노출]
D --> E{닫기 버튼 클릭}
E --> F[오늘 하루 보지 않기 체크?]
F -->|Yes| G[24시간 동안 노출 안 함]
F -->|No| H[다음 접속 시 다시 노출]
E --> I[다음 순위 팝업 노출]
적합한 활용:
- 신규 기능 안내 (한 번만 알려주면 됨)
- 이벤트 시작 알림 (반복 알림 불필요)
- 약관 변경 고지 (동의 후 재표시 불필요)
flowchart LR
A[서버 이슈 발생] --> B[즉시 팝업 생성]
B --> C[우선순위: 1]
C --> D[한번만 노출: 끔]
D --> E[게시]
style A fill:#ffcdd2
style E fill:#c8e6c9
Q: 팝업이 너무 많으면 어떻게 되나요?
A: 우선순위에 따라 순차적으로 표시됩니다. 유저가 첫 번째 팝업을 닫으면 두 번째 팝업이 나타납니다. 너무 많은 팝업은 유저 경험에 좋지 않으니 5개 이내로 유지하세요.
Q: "한번만 노출"을 설정했는데 유저가 다시 보고 싶어합니다.
A: "한번만 노출"은 유저 기기에 쿠키/로컬 스토리지로 기록됩니다. 유저가 앱을 재설치하거나 브라우저 데이터를 삭제하면 다시 표시됩니다.
Q: 팝업에 이미지를 넣을 수 있나요?
A: 현재 인게임 팝업은 Plain Text만 지원합니다. 이미지가 필요하면 서비스 공지(Rich HTML)를 활용하고, 팝업에서는 "자세한 내용은 공지사항을 확인해 주세요"라고 안내하세요.
증상: "한번만 노출"을 설정했는데 유저에게 반복적으로 표시됨
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 앱 재설치 | 정상 동작 - 재설치 시 기록 초기화 |
| 다른 기기 접속 | 정상 동작 - 기기별 기록 |
| 팝업 ID 변경 | 팝업 수정 시 ID 유지 확인 |
증상: 활성화한 팝업이 게임 접속 시 표시되지 않음
원인 및 해결:
| 원인 | 해결 방법 |
|---|---|
| 사용 여부 비활성화 | 토글 상태 확인 |
| 기간 설정 오류 | 시작/종료 일시 확인 |
| 플랫폼 대상 불일치 | 유저 플랫폼에 맞는 대상 설정 확인 |
| 이미 본 것으로 기록됨 | "한번만 노출"이 켜져 있고 이미 확인한 경우 |
클릭하여 새 창에서 재생하세요.
이전 장: ← 제 7장: 공지사항 관리
다음 장: 제 9장: 쿠폰 관리 →
쿠폰은 마케팅, 보상, 프로모션에 필수적인 기능입니다. 이벤트 보상, 사전 예약 혜택, 협찬 코드 등 다양한 용도로 활용됩니다.
경로: 게임 관리 (Game) → 쿠폰 → 쿠폰 정의 (Coupon Definitions)
필요 권한: coupons.manage
쿠폰 관리 페이지의 전체 화면입니다.
| 버튼 | 설명 |
|---|---|
| 쿠폰 생성 | 새로운 쿠폰을 정의합니다. |
| SDK 연동 가이드 | 클라이언트에서 쿠폰을 사용하는 API 문서를 제공합니다. |
| 컬럼 | 설명 |
|---|---|
| 이름 | 쿠폰 이름 (관리용) |
| 쿠폰 코드 | 실제 사용되는 쿠폰 코드 또는 코드 패턴 |
| 유형 | NORMAL(일반) / UNIQUE(고유) |
| 참여 보상 | 쿠폰 사용 시 지급되는 보상 |
| 사용률 | 사용된 코드 수 / 전체 발행 수 |
| 시작 | 쿠폰 유효 시작일 |
| 종료 | 쿠폰 유효 종료일 |
| 생성일 / 상태 | 생성 일시 및 현재 상태 |
| 작업 | 코드 확인, ✏️ 편집, 🗑️ 삭제 버튼 |
[쿠폰 생성] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.
| 섹션 | 항목 | 필수 | 설명 |
|---|---|---|---|
| 기본 설정 | 사용중 | ✅ | 쿠폰 활성화 여부 |
| 기본 정보 | 이름 | ✅ | 쿠폰 이름 (관리용) |
| 설명 | 쿠폰에 대한 부가 설명 | ||
| 대상 지정 | 대상 플랫폼 | 사용 가능한 플랫폼 제한 | |
| 대상 채널 | 사용 가능한 채널 제한 | ||
| 코드 및 수량 | 유형 | ✅ | NORMAL(공용) / UNIQUE(개별 생성) |
| 코드 패턴 | 코드 생성 패턴 (영문+숫자 등) | ||
| 발행 수량 | 생성할 쿠폰 코드 개수 | ||
| 사용 제한 | 유저별 사용 횟수 | 한 유저가 사용할 수 있는 최대 횟수 | |
| 사용 가능 기간 | 쿠폰 유효 기간 (시작~종료) |
모든 유저가 동일한 코드를 사용합니다.
flowchart LR
A[유저: 쿠폰 입력] --> B[게임 서버]
B --> C[Gatrix: 코드 검증]
C --> B
B --> D[우편함으로 보상 지급]
style C fill:#fff9c4
특징:
- 한 개의 코드로 여러 유저가 사용
- SNS, 커뮤니티에 코드 공개 시 적합
- 총 발행 수량 = 전체 사용 가능 횟수
예시: 이벤트 프로모션 코드 SUMMER2024
유저마다 고유한 코드가 생성됩니다.
flowchart LR
A[유저 A] --> B[코드: ABC1-2345]
C[유저 B] --> D[코드: DEF6-7890]
E[유저 C] --> F[코드: GHI0-1234]
style B fill:#c8e6c9
style D fill:#c8e6c9
style F fill:#c8e6c9
특징:
- 유저마다 다른 코드 발급
- 코드 유출 방지
- 개인별 추적 가능
예시: 사전 예약 보상, VIP 전용 쿠폰
flowchart TD
subgraph 관리자["👨💼 관리자 (Gatrix)"]
A[쿠폰 정의 생성] --> B{유형 선택}
B -->|NORMAL| C[공용 코드 1개 생성]
B -->|UNIQUE| D[개별 코드 N개 생성]
end
subgraph 배포["📤 코드 배포"]
C --> E[SNS/커뮤니티 공개]
D --> F[이메일/DM 개별 발송]
end
subgraph 사용자["🎮 유저"]
E --> G[코드 입력]
F --> G
G --> H[보상 수령]
end
style A fill:#e3f2fd
style H fill:#c8e6c9
쿠폰 사용 시 지급될 보상을 설정합니다.
미리 정의된 보상 템플릿을 선택하여 간편하게 설정할 수 있습니다.
JSON 형식으로 보상 내용을 직접 입력합니다.
{
"items": [
{ "itemId": "gold", "quantity": 1000 },
{ "itemId": "gem", "quantity": 50 }
]
}
flowchart LR
A[사전 예약 명단<br/>10,000명] --> B[UNIQUE 쿠폰 생성<br/>10,000개]
B --> C[코드 다운로드<br/>CSV 파일]
C --> D[이메일 발송<br/>개별 코드 전달]
style B fill:#e3f2fd
style D fill:#c8e6c9
flowchart LR
A[프로모션 기획] --> B[NORMAL 쿠폰 생성<br/>코드: YOUTUBE2024]
B --> C[사용 제한: 10,000회]
C --> D[유튜버에게 코드 전달]
D --> E[영상으로 공개]
style B fill:#e3f2fd
style E fill:#c8e6c9
YOUTUBE2024 (직접 지정)Q: 쿠폰 코드를 직접 지정할 수 있나요?
A: NORMAL 쿠폰의 경우 코드를 직접 지정할 수 있습니다. UNIQUE 쿠폰은 패턴에 따라 자동 생성됩니다.
Q: 발급된 쿠폰 코드를 확인하려면?
A: 쿠폰 목록에서 해당 쿠폰의 [발행된 코드 수]를 클릭하면 발급된 코드 목록을 확인할 수 있습니다. CSV로 다운로드도 가능합니다.
Q: 쿠폰 사용 내역을 추적할 수 있나요?
A: 네, 감사 로그(Audit Log)에서 쿠폰 사용 내역을 확인할 수 있습니다. 또한 쿠폰별 사용률도 목록에서 바로 확인 가능합니다.
Q: 이미 발급된 쿠폰을 비활성화하면?
A: 쿠폰을 비활성화하면 더 이상 새로운 사용이 불가능합니다. 이미 사용된 보상은 회수되지 않습니다.
이전 장: ← 제 9장: 인게임 팝업 관리
다음 장: 제 11장: 설문조사 관리 →
게임 내 설문조사를 만들어 유저 의견을 수집하고 분석할 수 있습니다. 설문 참여 보상을 통해 참여율을 높일 수 있습니다.
경로: 게임 관리 (Game) → 설문지 (Surveys)
필요 권한: surveys.manage
설문조사 관리 페이지의 전체 화면입니다.
| 버튼 | 설명 |
|---|---|
| 설문 추가 | 새로운 설문조사를 생성합니다. |
| 컬럼 | 설명 |
|---|---|
| 설문 ID | 플랫폼별 설문 고유 식별자 |
| 제목 | 설문조사 제목 |
| 발동 조건 | 설문이 표시되는 조건 |
| 보상 | 설문 참여 시 지급되는 보상 |
| 상태 | 활성(Active) / 비활성(Inactive) |
| 생성일 | 설문 생성 일시 |
| 작업 | ✏️ 편집, 🗑️ 삭제 버튼 |
| 항목 | 필수 | 설명 |
|---|---|---|
| 설문 ID | ✅ | 플랫폼별 고유 식별자 |
| 제목 | ✅ | 설문조사 제목 |
| 설명 | 설문에 대한 부가 설명 | |
| 상태 | 활성화 여부 |
설문이 유저에게 표시되는 조건을 설정합니다.
| 조건 | 설명 |
|---|---|
| 즉시 표시 | 조건 없이 바로 표시 |
| 특정 레벨 도달 | 게임 내 특정 레벨 이상 |
| 플레이 시간 | 일정 플레이 시간 경과 후 |
| 스테이지 클리어 | 특정 스테이지 완료 후 |
유저 참여를 유도하기 위해 보상을 설정할 수 있습니다.
flowchart LR
A[설문 완료] --> B[보상 지급]
B --> C[아이템/재화 수령]
style B fill:#c8e6c9
| 보상 종류 | 예시 |
|---|---|
| 게임 재화 | 골드 1,000, 젬 50 |
| 아이템 | 가챠 티켓 1장 |
| 쿠폰 | 설문 참여 감사 쿠폰 |
수집된 설문 결과를 분석하여 게임 개선에 활용합니다.
Q: 설문을 특정 유저에게만 보여줄 수 있나요?
A: 네, 발동 조건을 설정하여 특정 조건을 만족하는 유저에게만 표시할 수 있습니다.
Q: 보상이 중복 지급되지 않나요?
A: 기본적으로 유저당 1회만 참여 및 보상 지급이 가능합니다.
이전 장: ← 제 10장: 쿠폰 관리
다음 장: 제 12장: 배너 관리 →
게임 내 상점에서 판매되는 상품들을 관리합니다. 주로 기획 데이터 동기화를 통해 상품이 등록되며, 대시보드에서는 판매 상태와 세부 설정을 조정할 수 있습니다.
경로: 게임 관리 (Game) → 스토어 상품관리 (Store Products)
필요 권한: store-products.manage
상점 상품 관리 페이지의 전체 화면입니다.
| 버튼 | 설명 |
|---|---|
| 상품 추가 | 새 상품 추가 (기획 데이터 동기화 권장) |
| 배치 프로세스 | 여러 상품 일괄 처리 |
| 컬럼 | 설명 |
|---|---|
| 판매여부 | 현재 판매 중 여부 |
| CMS ID | 기획 데이터 시스템 ID |
| 상품 ID | 상품 고유 식별자 |
| 상품명 | 상품 표시 이름 |
| 스토어 | 판매 스토어 (IAP, 인게임 등) |
| 가격 | 판매 가격 |
| 시작/종료 | 판매 기간 |
| 태그 | 분류용 태그 |
| 작업 | ✏️ 편집, 🗑️ 삭제 버튼 |
상점 상품은 주로 기획 데이터(Excel/JSON)에서 정의되어 동기화됩니다.
flowchart LR
A[Excel 기획서] --> B[데이터 빌드]
B --> C[Gatrix 업로드]
C --> D[상품 자동 등록]
style D fill:#c8e6c9
대시보드에서 직접 상품을 추가할 수도 있습니다.
| 상태 | 설명 |
|---|---|
| 판매 중 | 유저가 구매 가능 |
| 판매 중지 | 목록에서 숨김 |
| 기간 한정 | 특정 기간에만 판매 |
flowchart TD
A[상품 등록] --> B{기간 설정?}
B -->|설정함| C[시작~종료일 지정]
B -->|설정 안함| D[상시 판매]
C --> E[기간 내 자동 판매]
style E fill:#c8e6c9
| 스토어 | 설명 | 결제 방식 |
|---|---|---|
| IAP | 인앱 결제 상품 | 실제 현금 |
| 인게임 | 게임 재화 상품 | 골드, 젬 등 |
| 이벤트 | 이벤트 한정 상품 | 재화/현금 혼합 |
여러 상품을 한 번에 처리할 때 사용합니다.
| 작업 | 설명 |
|---|---|
| 일괄 판매 시작 | 선택한 상품들 판매 시작 |
| 일괄 판매 중지 | 선택한 상품들 판매 중지 |
| 일괄 삭제 | 선택한 상품들 삭제 |
Q: 상품 가격을 변경하면 기존 구매자에게 영향이 있나요?
A: 아니요, 가격 변경은 이후 구매에만 적용됩니다. 기존 구매는 영향받지 않습니다.
Q: 기획 데이터와 충돌하면 어떻게 되나요?
A: 기획 데이터 동기화 시 최신 데이터로 덮어씌워집니다. 대시보드에서 수정한 내용은 유지하려면 기획 측에 반영을 요청하세요.
이전 장: ← 제 11장: 설문조사 관리
다음 장: 제 13장: 배너 관리 →
게임 내 배너는 이벤트 홍보, 상품 광고, 신규 콘텐츠 안내 등에 활용됩니다. Gatrix에서는 시퀀스 기반의 동적 배너를 생성하고 관리할 수 있습니다.
경로: 게임 관리 (Game) → 배너 관리 (Banner Management)
필요 권한: banners.manage
배너 관리 페이지의 전체 화면입니다.
| 버튼 | 설명 |
|---|---|
| 배너 추가 | 새로운 배너를 생성합니다. |
| 컬럼 | 설명 |
|---|---|
| 이름 | 배너 이름 (관리용) |
| 설명 | 배너에 대한 부가 설명 |
| 크기 | 배너 사이즈 (예: 1024×512) |
| 시퀀스 | 배너에 포함된 프레임/시퀀스 수 |
| 상태 | 활성(Active) / 비활성(Inactive) |
| 버전 | 배너 버전 (수정 시 버전 업) |
| 생성일 | 배너 생성 일시 |
| 작업 | ✏️ 편집, 🗑️ 삭제 버튼 |
[배너 추가] 버튼을 클릭하면 아래와 같은 폼이 나타납니다.
| 섹션 | 항목 | 필수 | 설명 |
|---|---|---|---|
| 기본 정보 | 이름 | ✅ | 배너 이름 (예: main_banner, event_2024) |
| 설명 | 배너에 대한 부가 설명 | ||
| 크기 프리셋 | ✅ | 배너 사이즈 선택 (예: 1024×512) | |
| 재생 속도 | 시퀀스 전환 속도 (초 단위) | ||
| 사용 | 배너 활성화 여부 | ||
| 시퀀스 | 시퀀스 목록 | 배너에 포함될 프레임들 | |
| 미리보기 | 배너 미리보기 | 실시간으로 배너 렌더링 결과 확인 |
Gatrix 배너는 여러 시퀀스(프레임)로 구성됩니다.
flowchart LR
A[시퀀스 1<br/>이벤트 A] --> B[시퀀스 2<br/>이벤트 B]
B --> C[시퀀스 3<br/>신규 상품]
C --> A
style A fill:#e3f2fd
style B fill:#c8e6c9
style C fill:#fff9c4
| 항목 | 설명 |
|---|---|
| 이미지 URL | 배너 프레임 이미지 경로 |
| 링크 URL | 클릭 시 이동할 URL (선택) |
| 노출 시간 | 해당 프레임 표시 시간 |
| 순서 | 프레임 표시 순서 |
게임 내 배치 위치에 따라 적절한 크기를 선택합니다.
| 프리셋 | 크기 | 권장 용도 |
|---|---|---|
| 1024×512 (2:1) | 가로형 | 메인 배너, 이벤트 배너 |
| 512×512 (1:1) | 정사각형 | 아이콘, 썸네일 |
| 512×1024 (1:2) | 세로형 | 사이드 배너, 팝업 |
flowchart LR
A[배너 1] -->|5초| B[배너 2]
B -->|5초| C[배너 3]
C -->|5초| A
flowchart TD
A[신규 이벤트 기획] --> B[배너 이미지 제작]
B --> C[시퀀스 추가]
C --> D[미리보기 확인]
D --> E{만족?}
E -->|예| F[저장 및 배포]
E -->|아니오| C
style F fill:#c8e6c9
Q: 배너 이미지는 어디에 업로드하나요?
A: 배너 이미지는 별도의 CDN이나 이미지 호스팅 서비스에 업로드한 후, URL을 입력합니다. Gatrix에서는 이미지 URL만 관리합니다.
Q: 시퀀스 순서를 변경하려면?
A: 시퀀스 목록에서 드래그 앤 드롭으로 순서를 변경할 수 있습니다.
이전 장: ← 제 11장: 상점 상품 관리
다음 장: 제 13장: 기획 데이터 관리 →
기획 데이터는 게임의 밸런스, 아이템 정보, 스테이지 설정 등 핵심 콘텐츠 데이터를 관리합니다. Excel로 작성된 기획 데이터를 JSON으로 변환하여 게임에 적용합니다.
경로: 게임 관리 (Game) → 기획데이터 → 기획데이터 관리
필요 권한: planning-data.manage
flowchart LR
A[Excel 수정] --> B[Gatrix 업로드]
B --> C[자동 검증]
C -->|성공| D[JSON 변환 및 배포]
C -->|실패| E[에러 리포트]
style D fill:#c8e6c9
style E fill:#ffcdd2
| 버튼 | 설명 |
|---|---|
| 새로고침 | 현재 데이터 목록 새로고침 |
| 기획데이터 업로드 | 새로운 기획 데이터 업로드 |
기획 데이터를 업로드하는 방법은 크게 3가지입니다.
CMS 폴더의 원본 데이터를 JSON 파일로 변환하는 과정입니다.
flowchart LR
A[CMS 폴더<br/>원본 데이터] --> B[데이터 빌드<br/>yarn 명령]
B --> C[JSON 파일<br/>언어별 생성]
C --> D[Gatrix 업로드]
style A fill:#e3f2fd
style D fill:#c8e6c9
CLI 명령어:
# 프로젝트 루트에서 실행 (권장)
yarn planning-data:convert
# 옵션 사용
yarn planning-data:convert --input <CMS폴더경로> --output <출력폴더경로>
# 도움말 보기
yarn planning-data:convert --help
옵션 설명:
| 옵션 | 설명 | 기본값 |
|---|---|---|
--input <path> |
CMS 폴더 경로 | ./packages/backend/cms |
--output <path> |
출력 폴더 경로 | ./packages/backend/data/planning |
--verbose |
상세 로깅 | - |
빌드된 JSON 파일들을 원격 Gatrix 서버에 업로드합니다.
# 기본 사용법
yarn upload-planning-data \
--api-url=https://gatrix.example.com \
--env=production \
--dir=./packages/backend/data/planning \
--token=<SERVER_API_TOKEN>
# 업로더 이름 및 코멘트 추가 (CI/CD용)
yarn upload-planning-data \
--api-url=https://gatrix.example.com \
--env=qa \
--dir=./planning-data \
--token=$GATRIX_API_TOKEN \
--uploader="Jenkins CI" \
--comment="Build #123"
옵션 설명:
| 옵션 | 필수 | 설명 |
|---|---|---|
--api-url |
✅ | Gatrix 백엔드 API URL |
--env |
✅ | 대상 환경 (dev, qa, production) |
--dir |
✅ | 업로드할 JSON 파일이 있는 폴더 |
--token |
✅ | Server API 토큰 (환경변수 GATRIX_API_TOKEN으로도 설정 가능) |
--uploader |
업로더 이름 (예: "Jenkins CI") | |
--comment |
업로드 코멘트 |
flowchart TD
subgraph 기획팀["📊 기획팀"]
A[Excel 파일 작성] --> B[버전 관리<br/>Git/SVN]
end
subgraph 빌드["🔨 데이터 빌드"]
B --> C[Excel → JSON 변환]
C --> D[JSON 검증]
end
subgraph Gatrix["📡 Gatrix"]
D --> E[기획데이터 업로드]
E --> F[버전 생성]
F --> G[환경별 배포]
end
subgraph 게임["🎮 게임 서버"]
G --> H[Development]
G --> I[Staging]
G --> J[Production]
end
style A fill:#e3f2fd
style J fill:#c8e6c9
업로드된 기획 데이터는 버전으로 관리됩니다.
| 항목 | 설명 |
|---|---|
| 버전 | 업로드 시 자동 생성되는 버전 번호 |
| 업로드 일시 | 데이터 업로드 시간 |
| 업로더 | 업로드한 관리자 |
| 변경 내역 | 이전 버전과의 차이점 |
| 롤백 | 이전 버전으로 되돌리기 |
데이터 문제 발생 시 이전 버전으로 롤백할 수 있습니다.
flowchart TD
A[문제 발생!<br/>v1.2.0 버그] --> B[히스토리 확인]
B --> C[v1.1.0 선택]
C --> D[롤백 실행]
D --> E[이전 버전 적용]
style A fill:#ffcdd2
style E fill:#c8e6c9
Q: 기획 데이터 형식은 무엇인가요?
A: Excel(.xlsx) 또는 JSON 형식을 지원합니다. Excel 파일은 빌드 과정에서 JSON으로 자동 변환됩니다.
Q: 환경별로 다른 데이터를 적용할 수 있나요?
A: 네, 환경(Development, Staging, Production)별로 다른 버전의 데이터를 배포할 수 있습니다.
Q: 롤백하면 현재 데이터는 어떻게 되나요?
A: 롤백해도 현재 버전의 데이터는 히스토리에 남아있습니다. 언제든지 다시 적용할 수 있습니다.
이전 장: ← 제 12장: 배너 관리
다음 장: 제 14장: 리모트 컨피그 →
리모트 컨피그는 앱 업데이트 없이 게임의 동작을 원격으로 제어할 수 있는 기능입니다. A/B 테스트, 기능 플래그, 동적 설정 변경 등에 활용됩니다.
경로: 관리자 패널 (Admin Panel) → 리모트 설정 (Remote Setting)
필요 권한: remote-config.manage
리모트 컨피그 관리 페이지의 전체 화면입니다.
| 탭 | 설명 |
|---|---|
| 파라미터 | 기본 설정 값 관리 |
| 캠페인 | A/B 테스트 캠페인 관리 |
| 컨텍스트 필드 | 유저 속성 필드 정의 |
| 세그먼트 | 유저 그룹 세분화 |
| 변형 | 실험 변형(Variant) 관리 |
| 배포 히스토리 | 배포 이력 확인 |
게임에서 사용하는 설정 값들을 정의하고 관리합니다.
| 컬럼 | 설명 |
|---|---|
| 파라미터 키 | 고유 식별자 (예: welcome_message) |
| 타입 | 데이터 타입 (String, Number, Boolean, JSON) |
| 기본값 | 기본 설정 값 |
| 설명 | 파라미터에 대한 설명 |
| 기능 | 적용된 기능 플래그 |
| 마지막 업데이트 | 최근 수정 일시 |
| 타입 | 용도 예시 |
|---|---|
| String | 공지 메시지, URL, 텍스트 |
| Number | 보너스 배율, 타이머 값 |
| Boolean | 기능 On/Off 플래그 |
| JSON | 복잡한 설정 객체 |
flowchart TD
subgraph Gatrix["🖥️ Gatrix 대시보드"]
A[파라미터 정의] --> B[캠페인 생성<br/>A/B 테스트]
B --> C[세그먼트 지정]
C --> D[배포]
end
subgraph 게임["🎮 게임 클라이언트"]
E[SDK 초기화] --> F[컨피그 요청]
F --> G[설정 값 수신]
G --> H[게임에 적용]
end
D --> F
style D fill:#e3f2fd
style H fill:#c8e6c9
특정 유저 그룹에게 다른 설정 값을 적용하여 효과를 비교합니다.
flowchart LR
A[전체 유저] --> B{세그먼트 분류}
B -->|그룹 A<br/>50%| C[기존 UI]
B -->|그룹 B<br/>50%| D[신규 UI]
C --> E[지표 수집]
D --> E
E --> F[결과 분석]
style C fill:#e3f2fd
style D fill:#c8e6c9
| 항목 | 설명 |
|---|---|
| 캠페인 이름 | 실험 식별용 이름 |
| 대상 파라미터 | 변경할 파라미터 |
| 변형 (Variant) | 각 그룹별 설정 값 |
| 트래픽 배분 | 그룹별 유저 비율 (%) |
| 기간 | 캠페인 진행 기간 |
특정 조건을 만족하는 유저 그룹을 정의합니다.
| 조건 | 설명 | 예시 |
|---|---|---|
| 플랫폼 | OS 종류 | iOS, Android |
| 국가 | 접속 국가 | KR, US, JP |
| 앱 버전 | 클라이언트 버전 | >= 2.0.0 |
| 유저 레벨 | 게임 내 레벨 | >= 10 |
| VIP 등급 | 결제 등급 | Gold, Platinum |
flowchart LR
A[새 기능 개발 완료] --> B[5% 유저 활성화]
B --> C[모니터링 1주일]
C --> D{문제 없음?}
D -->|예| E[30% → 50% → 100%]
D -->|아니오| F[0%로 비활성화]
style E fill:#c8e6c9
style F fill:#ffcdd2
new_feature_enabled (Boolean)falsetrue 적용flowchart LR
A[버그 발견] --> B[파라미터 값 변경<br/>true → false]
B --> C[즉시 배포]
C --> D[앱 업데이트 없이<br/>기능 비활성화]
style A fill:#ffcdd2
style D fill:#c8e6c9
Q: 파라미터 변경이 즉시 반영되나요?
A: 배포 후 클라이언트가 다음 요청 시 새 값을 받습니다. 즉시 반영이 필요하면 클라이언트에서 폴링 주기를 조정하세요.
Q: 배포를 롤백할 수 있나요?
A: 네, 배포 히스토리 탭에서 이전 버전으로 롤백할 수 있습니다.
이전 장: ← 제 13장: 기획 데이터 관리
다음 장: 제 15장: 감사 로그 →
감사 로그는 대시보드에서 발생하는 모든 관리자 활동을 기록합니다. 보안 감사, 문제 추적, 책임 소재 확인에 필수적인 기능입니다.
경로: 관리자 패널 (Admin Panel) → 감사 로그 (Audit Log)
필요 권한: audit-logs.view
감사 로그 페이지의 전체 화면입니다.
| 필터 | 설명 |
|---|---|
| 오늘 | 오늘 발생한 로그만 표시 |
| 어제 | 어제 발생한 로그만 표시 |
| 7일 | 최근 7일 로그 |
| 1개월 | 최근 1개월 로그 |
| 사용자 지정 | 날짜 범위 직접 선택 |
| 사용자 검색 | 특정 사용자의 활동만 필터 |
| 컬럼 | 설명 |
|---|---|
| 생성일시 | 활동 발생 시간 |
| 사용자 | 활동을 수행한 관리자 |
| 작업 | 수행한 작업 종류 |
| 리소스 | 작업 대상 리소스 종류 |
| 리소스 ID | 작업 대상의 고유 ID |
| IP 주소 | 접속 IP |
| 이벤트 | 설명 | 리소스 |
|---|---|---|
| 서비스 공지 고정 | 공지사항 상단 고정 | 서비스 공지 |
| 게임 월드 순서 변경 | 월드 목록 순서 수정 | 게임 월드 |
| 월드 편집 | 월드 정보 수정 | 게임 월드 |
| 사용자 생성 | 새 관리자 계정 생성 | 사용자 |
| 사용자 편집 | 관리자 정보/권한 수정 | 사용자 |
| 쿠폰 생성 | 새 쿠폰 발행 | 쿠폰 |
| 로그인 | 대시보드 로그인 | 사용자 |
| 감사 로그 조회 | 감사 로그 확인 | 감사 로그 |
flowchart LR
A[공지 오타 발견] --> B[감사 로그 접속]
B --> C[리소스: 서비스 공지<br/>검색]
C --> D[수정 내역 확인]
D --> E[담당자 파악]
style E fill:#c8e6c9
flowchart TD
A[보안 감사 요청] --> B[기간 설정<br/>지난 1개월]
B --> C[모든 '사용자 생성'<br/>이벤트 필터]
C --> D[비정상 패턴 확인]
style D fill:#fff9c4
각 로그 항목을 클릭하면 상세 정보를 확인할 수 있습니다.
| 정보 | 설명 |
|---|---|
| 변경 전 데이터 | 수정 전 상태 (JSON) |
| 변경 후 데이터 | 수정 후 상태 (JSON) |
| 요청 정보 | HTTP 메서드, 경로 등 |
| 사용자 에이전트 | 접속 브라우저/기기 정보 |
Q: 감사 로그는 얼마나 오래 보관되나요?
A: 기본적으로 90일간 보관됩니다. 보관 기간은 시스템 설정에서 조정할 수 있습니다.
Q: 감사 로그를 CSV로 내보낼 수 있나요?
A: 현재 버전에서는 화면에서 조회만 가능합니다. 내보내기가 필요하면 데이터베이스 담당자에게 문의하세요.
Q: 특정 사용자의 모든 활동을 추적하려면?
A: 검색창에 사용자 이메일을 입력하면 해당 사용자의 모든 활동 로그가 필터링됩니다.
이전 장: ← 제 14장: 리모트 컨피그
다음 장: 제 16장: API 토큰 관리 →
API 토큰은 외부 시스템(게임 서버, Edge 서버, CI/CD 파이프라인 등)이 Gatrix API에 접근할 때 인증에 사용됩니다.
경로: 관리자 패널 (Admin Panel) → 보안 (Security) → API 액세스 토큰
필요 권한: api-tokens.manage
🎬 영상 가이드: API 토큰 관리 방법 보기
API 토큰 관리 페이지의 전체 화면입니다.
| 버튼 | 설명 |
|---|---|
| 토큰 생성 | 새로운 API 토큰을 생성합니다. |
| 컬럼 | 설명 |
|---|---|
| 토큰 이름 | 토큰 식별용 이름 |
| 토큰 유형 | API / Edge |
| 환경 | 적용 환경 (dev, staging, production 등) |
| 설명 | 토큰 용도 설명 |
| 사용 횟수 | 토큰이 사용된 횟수 |
| 마지막 사용일 | 최근 사용 일시 |
| 만료일 | 토큰 만료 예정일 |
| 생성일 | 토큰 생성 일시 |
| 작업 | 복사, ✏️ 편집, 🔄 재생성, 🗑️ 삭제 버튼 |
게임 서버가 Gatrix 백엔드 API를 호출할 때 사용합니다.
flowchart LR
A[게임 서버] -->|Server Token| B[Gatrix Backend API]
B --> C[데이터 조회/수정]
style B fill:#e3f2fd
용도:
- 점검 상태 조회
- 공지사항 조회
- 쿠폰 검증
- 기획 데이터 동기화
Edge 서버가 Gatrix Edge API를 호출할 때 사용합니다.
flowchart LR
A[게임 클라이언트] --> B[Edge 서버]
B -->|Edge Token| C[Gatrix Edge API]
style C fill:#c8e6c9
[토큰 생성] 버튼을 클릭하여 새 토큰을 생성합니다.
| 항목 | 필수 | 설명 |
|---|---|---|
| 이름 | ✅ | 토큰 식별용 이름 (예: game-server-prod) |
| 유형 | ✅ | API / Edge 선택 |
| 환경 | ✅ | 적용 환경 선택 |
| 설명 | 토큰 용도 메모 | |
| 만료일 | 토큰 유효 기간 (비워두면 무기한) |
토큰은 생성 시 한 번만 전체 값이 표시됩니다. 이후에는 마스킹된 형태로만 확인 가능합니다.
flowchart TD
A[토큰 생성] --> B[전체 값 표시<br/>⚠️ 이때만 복사 가능!]
B --> C[환경변수에 저장]
C --> D[안전한 곳에 백업]
style B fill:#fff9c4
⚠️ 중요: 토큰 값을 분실하면 재생성해야 합니다. 재생성하면 기존 토큰은 무효화됩니다.
보안상의 이유로 토큰을 변경해야 할 때 사용합니다.
보안을 위해 환경별로 별도의 토큰을 사용하는 것이 좋습니다.
| 환경 | 토큰 예시 | 보안 수준 |
|---|---|---|
| Development | dev-api-token | 🟢 낮음 |
| Staging | staging-api-token | 🟡 중간 |
| Production | prod-api-token | 🔴 높음 |
💡 원칙: Production 토큰은 최소한의 인원만 접근 가능하도록 관리하세요.
curl -X GET https://api.gatrix.com/v1/game-worlds \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"
const GATRIX_API_TOKEN = process.env.GATRIX_API_TOKEN;
const response = await fetch('https://api.gatrix.com/v1/game-worlds', {
headers: {
'Authorization': `Bearer ${GATRIX_API_TOKEN}`,
'Content-Type': 'application/json'
}
});
Q: 토큰이 유출되었을 때 어떻게 하나요?
A: 즉시 해당 토큰의 [🔄 재생성] 버튼을 클릭하여 무효화하세요. 그리고 새 토큰을 서버에 적용하세요.
Q: 토큰에 만료일을 설정하는 것이 좋나요?
A: 보안 정책에 따라 다릅니다. 정기적인 토큰 교체가 필요하면 만료일을 설정하고, 만료 전에 재생성하세요.
Q: 사용 횟수가 비정상적으로 높으면?
A: 토큰 유출 또는 시스템 오류의 징후일 수 있습니다. 감사 로그를 확인하고 필요시 토큰을 재생성하세요.
클릭하여 새 창에서 재생하세요.
이전 장: ← 제 15장: 감사 로그
본 문서는 시스템 엔지니어 및 서버 관리자를 위한 설정 가이드입니다.
Gatrix의 이메일 발송 기능을 활성화하기 위한 SMTP 설정 방법을 안내합니다.
Gatrix는 사용자 초대, 비밀번호 재설정 등을 위해 SMTP 서버가 필요합니다.
서버 배포 시 아래 환경 변수(Environment Variables)를 설정해야 합니다.
| 변수명 | 설명 | 예시 |
|---|---|---|
SMTP_HOST |
SMTP 서버 주소 | smtp.gmail.com 또는 email-smtp.us-east-1.amazonaws.com |
SMTP_PORT |
포트 번호 | 587 (TLS) 또는 465 (SSL) |
SMTP_USER |
SMTP 사용자 계정 | admin@gatrix.com |
SMTP_PASS |
SMTP 비밀번호 | app-password-xxxx |
SMTP_FROM |
발신자 주소 | "Gatrix Support" <noreply@gatrix.com> |
SMTP_SECURE |
보안 연결 사용 여부 | true 또는 false |
Google 계정 설정에서 앱 비밀번호 (App Password)를 생성하여 사용해야 합니다.
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=xxxx-xxxx-xxxx-xxxx
SMTP_SECURE=false
프로덕션 환경에서 가장 권장되는 방식입니다.
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=AKIAxxxxxxxxxxxx
SMTP_PASS=Bxxxxxxxxxxxxxxxxxxxx
SMTP_SECURE=true
본 매뉴얼 또는 Gatrix 시스템에 대해 질문이 있으시면 Gatrix 개발팀에 문의해 주세요.
💡 Tip: 문의 시 환경(Environment), 오류 메시지, 재현 절차를 함께 알려주시면 더 빠른 지원이 가능합니다.